# Auth API

Version: v2

## Servers

Sandbox URL
```
https://api-ext-sboxmeta.partners.spotnana.com
```

## Security

### Bearer

Type: http
Scheme: bearer

## Download OpenAPI description

[Auth API](https://developer-docs.redocly.app/docs/_bundle/openapi/AuthApi.yaml)

## Authentication

Authentication APIs for user login, logout, and token management

### Get oauth2 token

 - [POST /v2/auth/oauth2-token](https://developer-docs.redocly.app/docs/openapi/authapi/authentication/fetchoauth2token.md): Get oauth2 token using the client credentials.
{% admonition type="warning" %}
Note: API calls to the /v2/auth/oauth2-token and /get-auth-token (legacy) endpoints are rate limited.
We recommend reusing the existing tokens until they expire.
{% /admonition %}

## API User

### Create a new API user

 - [POST /v2/api-users](https://developer-docs.redocly.app/docs/openapi/authapi/api-user/createapiuser.md): Creates a new API user (also known as a machine user) that your application
can use to authenticate with Spotnana APIs. Each API user is scoped to a specific TMC and role,
giving you control over what level of access the credentials grant.

Use this endpoint to:
- Generate a dedicated clientId and clientSecret pair that your backend services can use to obtain access tokens.
- Assign either a TMC admin or a company admin role to scope what the API user can do across your organization.
- 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.

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.).

Notes:
- Store the clientSecret or scimToken securely. They are only returned once at creation and cannot be retrieved later.
- You can create up to 5 API users per TMC. To increase this limit, contact your Spotnana representative.
- Only a TMC admin can use this endpoint to create API users.
- SCIM_TOKEN credential type requires role to be COMPANY_ADMIN.

### Get API users for a TMC

 - [GET /v2/api-users](https://developer-docs.redocly.app/docs/openapi/authapi/api-user/getapiusers.md): 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.

### Delete an API user

 - [POST /v2/api-users/revoke](https://developer-docs.redocly.app/docs/openapi/authapi/api-user/deleteapiuser.md): 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.

### Rotate client secret for an API user

 - [POST /v2/api-users/rotate](https://developer-docs.redocly.app/docs/openapi/authapi/api-user/rotateclientsecret.md): 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.