Auth API (v2)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Creates a new API user (also known as a machine user) that your application can use to authenticate with Spotnana APIs.

Use this endpoint to:

• Generate a dedicated clientId and clientSecret pair that your backend services can use to obtain access tokens.
• Create a SCIM API user by setting credentialType to SCIM_TOKEN with role set to COMPANY_ADMIN. This returns a SCIM bearer token instead of a client secret.

Role assignment:

• With role: The API user is automatically added to the corresponding RBAC user group (TMC Admin or Company Admin) based on the specified role. Requires tmcId for TMC admin, or both orgId and tmcId for company admin.

• Without role: The API user is created without any RBAC roles. Requires orgId. Use this option for granular permission control — assign specific RBAC groups or roles to the returned userId via the RBAC assignment endpoints.

Credential types:

• CLIENT_CREDENTIALS (default): Returns a clientId and clientSecret. Use them in POST /v2/auth/oauth2-token to obtain an access token.
• SCIM_TOKEN: Returns a SCIM bearer token instead of a client secret. Requires role set to COMPANY_ADMIN.

Next steps:

• For CLIENT_CREDENTIALS (default): Use the clientId and clientSecret in the POST /v2/auth/oauth2-token endpoint to obtain an access token.
• For SCIM_TOKEN: Use the returned scimToken as the Bearer token in the Authorization header for SCIM API requests (/v2/scim/Users, etc.).
• If created without role: Use the returned userId with POST /v3/user-groups/{userGroupId}/members to add the user to RBAC groups, or POST /v3/users/{userId}/roles to assign roles directly.

Notes:

• Store the clientSecret or scimToken securely. They are only returned once at creation and cannot be retrieved later.
• There is a fixed limit on the number of API users per TMC. To increase this limit, contact your Spotnana representative.

Retrieves the list of all active API users associated with the caller's TMC.

Use this endpoint to:

• Audit existing API users and their clientIds under a TMC.
• Look up the clientId for a specific API user before rotating its client secret or revoking access.

Notes:

• This endpoint supports pagination using limit and offset query parameters.
• The response includes only the clientId for each user. The clientSecret is never returned.
• Returns only the API users belonging to the caller's contracting TMC.
• Only a TMC admin can use this endpoint.

Permanently deletes an API user and revokes its access to the Spotnana platform. This immediately invalidates all existing access tokens and removes the API user's ability to authenticate.

Use this endpoint to:

• Revoke access for an API user that is no longer needed.
• Decommission an integration or clean up unused API users.
• Free up a slot in your TMC's API user quota (default up to 5 API users per TMC).

Best practice:

Before revoking, ensure no active integrations are using this clientId. Be sure to:

1. create a new API user first
2. update your integrations to use the new credentials
3. verify they work
4. and then revoke the old API user.

Notes:

• This action is permanent and cannot be undone. The clientId and clientSecret are permanently invalidated.
• All active tokens for this API user are invalidated immediately. Any in-flight API requests using those tokens will fail.
• The API user being revoked must belong to the same TMC as the caller.
• Only a TMC admin can use this endpoint.

Generates a new clientSecret for an existing API user. The old clientSecret is immediately invalidated and all existing access tokens for the API user will be expired.

Use this endpoint to:

• Rotate credentials as part of a regular security hygiene practice.
• Replace a clientSecret without deleting the API user.
• Generate a new clientSecret if the old secret was lost or not stored.

Best practice:

• Update your integrations with the new clientSecret immediately after rotation. Any authentication requests using the old secret will fail.

Notes:

• The new clientSecret is only returned once in the response and cannot be retrieved later. Store it securely.
• The clientId remains the same.
• The old clientSecret stops working immediately. Any integration using it will need to re-authenticate with the new secret.
• All existing access tokens created using the old clientSecret are immediately invalidated.
• Only a TMC admin can use this endpoint.