Skip to main content
Marty uses API access tokens to authenticate API requests. API access tokens are generated directly within the Marty application, and each token can be configured with a specific set of permissions, called scopes. Scopes allow you to control exactly what an integration can access or perform through the API. Instead of granting access to the entire Marty API, you can create a token with only the permissions required for a specific use case. For example, an integration that only needs to retrieve assessment information can be given the Read Assessments scope, while an integration that needs to invite candidates can additionally be granted the Invite Candidates scope. API access tokens should always be treated as sensitive credentials and stored securely.

​
API access token scopes

Each API access token can be restricted to one or more scopes. The selected scopes determine which actions can be performed when using that token. Select only the scopes required by your integration. A token can contain multiple scopes if the integration requires access to several parts of the API. For example, an integration that needs to retrieve available assessments and invite candidates to them would require both Read Assessments and Invite Candidates. We recommend following the principle of least privilege and granting only the scopes that are necessary for the integration to work.

​
How to create an API access token

To generate a new API access token:
  1. Sign in to your Marty account.
  2. Open the Create API Access Token page: https://app.marty.hr/settings/api-access-tokens/create
  3. Enter a descriptive name in the Label field.
  4. Under Select scopes, choose the permissions required by your integration.
  5. Review the selected scopes.
  6. Click Create access token.
  7. Copy the generated token and store it securely.
Use a clear label that makes it easy to identify what the token is used for. For example:
  • ATS integration
  • Reporting service
  • Production integration
  • Development API
  • Internal automation
If you have multiple integrations or environments, we recommend creating separate tokens for each one. This makes it easier to manage permissions and revoke individual tokens when necessary.

​
Using the API access token

After creating the token, use it to authenticate requests to the Marty API according to the authentication format described for the relevant API endpoints. The permissions available to each request are determined by the scopes assigned to the token. If an API request requires a scope that the token does not have, the request will not be authorized to perform that action. For this reason, make sure that the token includes all scopes required by your integration while avoiding unnecessary permissions.

​
Keep your API access token secure

API access tokens provide access to Marty data and functionality according to their assigned scopes. They should be treated like passwords or other application secrets. Do not:
  • Commit API access tokens to source-code repositories.
  • Include them directly in client-side applications.
  • Share them in public documentation, tickets, or chat messages.
  • Store them in plain text when a secure alternative is available.
  • Expose them in application logs.
Where possible, store API access tokens in environment variables, a secrets manager, or another secure credential-management system. If a token is no longer needed or you believe it may have been exposed, revoke it and create a new one. For better security and easier administration, create separate API access tokens for different applications, integrations, and environments. For example, production and development environments should generally use different tokens. Using separate tokens makes it possible to:
  • Grant different scopes to different integrations.
  • Identify which integration is using a particular token.
  • Revoke one integration’s access without affecting others.
  • Reduce the impact of an accidentally exposed token.