Authentication

Every API call carries a bearer token from your tenant’s Identity:

Authorization: Bearer eyJhbGciOi…

A backend gets its token with an API client and the OAuth 2.0 client_credentials grant.

No static API keys

Every call carries a short-lived access token. A secret is never sent to the API itself: it is only exchanged for a token at your tenant’s token endpoint, with the client credentials grant (RFC 6749 §4.4).

API clients

An API client is an OAuth 2.0 client in your tenant that signs in with the client credentials grant: you exchange its client id and secret for a short-lived access token. Create one in the portal: open your tenant, go to Developer, and choose Create API client. You pick:

• a name;
• a role in the whole tenant: Reader (reads everything), Contributor (reads and changes everything except users, API clients and role assignments) or Owner (everything, including users, API clients and roles);
• how long the secret lives: 30, 90 or 365 days.

The portal shows the client id and the secret. The secret is shown once. Identity keeps only a hash of it.

The Developer section lists your API clients with their secrets (expired ones marked) and roles. From there you can issue a new secret, revoke a secret, or delete an API client with its role assignments. Give each backend its own API client with the least role it needs.

Get a token

POST https://auth.nimles.com/tenant/{tenantId}/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client id}&client_secret={secret}&scope=nimles.user

{ "access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 3600 }

See the Quickstart for curl and PowerShell. A wrong id or secret, or an expired or revoked secret, answers 401 with an OAuth error:

{
  "error": "invalid_client",
  "error_description": "The specified client credentials are invalid.",
  "error_uri": "https://documentation.openiddict.com/errors/ID2055"
}

The token is a JWT signed with RS256; the keys are at https://auth.nimles.com/tenant/{tenantId}/.well-known/jwks, and the discovery document at …/.well-known/openid-configuration.

Token lifetime

Access tokens live for one hour (expires_in: 3600). client_credentials gives no refresh token: ask for a new token when the old one is about to expire.

Cache the token and reuse it for every call until shortly before it expires. Do not get a token per request: the token endpoint allows 120 requests a minute per client address (see Limits).

Scopes

API clients ask for one scope, nimles.user. It is the scope of the platform’s APIs; what a token may then do is decided by the API client’s role, not by scopes. Other platform scopes are for Nimles’ own applications and are not granted to API clients.

Secrets

• A secret is generated by Identity: 32 random bytes, base64url-encoded. You never choose it.
• It expires after the lifetime chosen when it was issued (1 to 730 days through the API; 30, 90 or 365 in the portal). An expired secret stops working at once.
• An API client can have several secrets at a time, which is what makes rotation possible.

Rotate a secret

1. Issue a new secret for the API client (New secret in the Developer section).
2. Deploy it to your backend, and check that it gets tokens.
3. Revoke the old secret. It stops working at once.

Tokens already issued with the old secret stay valid until they expire, up to an hour.

Through the API, with a token that may change clients (an Owner):

POST https://api.nimles.com/identity/api/tenant/{tenantId}/Clients/{clientId}/secrets
Content-Type: application/json

{ "description": "backend, 2026", "expiresInDays": 365 }

The answer is 201 Created with the secret’s id, its value (only in this answer) and its expiration. Revoke a secret with DELETE …/Clients/{clientId}/secrets/{secretId}.

Users instead of API clients

Apps where people sign in use the authorization code flow with PKCE against the same issuer, https://auth.nimles.com/tenant/{tenantId}/, and call the API with the user’s token. Their roles decide what the app may do. Setting up such clients is not covered by the beta documentation yet.