# APIs

Protect your APIs as OAuth resources: define scopes, control machine-to-machine and user access, and set token format and lifetimes.

An **API** represents a protected resource that applications obtain access tokens for. Registering an API tells the platform the resource's identifier (its audience), the **scopes** (permissions) it exposes, which applications may call it, and how the access tokens it issues are shaped and signed.

You manage APIs under **Integrations → APIs** in the Admin Console.

## What an API is

Each API has:

- a **name**: a label for administrators, and
- an **identifier**: the audience value that appears in tokens issued for this API (for example, `https://api.example.com`).

On a custom API you can also name **contacts**, the employees to ask about it. They are purely informational and receive no rights.

There are two kinds:

- **System API**: the platform's own management API. Its name, identifier, and scopes are fixed and cannot be edited.
- **Custom API**: an API you register and govern. You define its scopes, who may call it, and its token settings.

## Scopes (permissions)

A scope is a single permission a token can carry, for example `read:documents` or `orders.write`.

- The **system API** exposes a fixed catalogue of management scopes (for example `users.read`, `users.write`, `groups.read`, `roles.write`, `logs.read`). These are the scopes you grant to applications that call the platform's own management API.
- A **custom API** exposes the scopes *you* define. On the API's permissions tab, add each scope with a name and a description. A few reserved OpenID Connect scopes (such as `openid`, `profile`, `email`, `offline_access`) cannot be redefined.

Some management scopes sit deliberately next to their base scope instead of being implied by it. The one to know is `users.mfa.read`, which covers a user's MFA enrollments (which second factors are registered, and when each was last used). It is required on **every** endpoint that returns a user, including the responses of create, update, delete and the deactivate and activate calls. A token holding only `users.read` or `users.write` receives the user without the enrollment list, so grant `users.mfa.read` in addition where an integration needs it.

## Who may call an API

Two independent policies control access, one for each kind of caller:

### User-delegated access

When an interactive application requests a token *on behalf of a signed-in user*, the API's **user policy** decides whether it is allowed:

- **Allow all**: any interactive application may request tokens for this API.
- **Require grant**: only applications you have explicitly granted may request tokens, and only for the scopes you grant them.
- **Deny all**: no interactive application may request tokens.

### Machine-to-machine access

When an application authenticates *as itself* with the client-credentials grant (no user involved), the API's **client policy** decides whether it is allowed:

- **Require grant**: only applications you have explicitly granted may request tokens, limited to the granted scopes.
- **Deny all**: no machine-to-machine application may request tokens.

### Granting an application

Where a policy is **require grant**, authorize an application from the API's **application access** tab:

1. Choose **Add application** in the user-delegated or the client (machine-to-machine) section.
2. Select the application.
3. Select the scopes to grant, or choose **grant all permissions** to include current and future scopes automatically.
4. Save. Tokens the platform issues to that application for this API now carry the granted scopes.

A machine-to-machine application is typically the *machine-to-machine* application type (see [Applications](https://dts-identity.com/docs/integrations/applications.md)).

[Image: The API list in the Admin Console]

## Test an API token

Once an API has at least one machine-to-machine application authorized for it (with the client-credentials grant), the API's **Test** tab lets you try a token end to end without writing code:

1. Select one of the authorized machine-to-machine applications.
2. The page shows a ready-to-run example **token request** against the token endpoint, using that application's client ID and secret and this API's identifier as the audience.
3. It shows the **token response** and decodes the issued access token into its **header**, **payload**, and **signature** so you can confirm the audience and granted scopes are what you expect.
4. It shows an example **API call** that sends the token as a `Bearer` header.

Copy the commands to run them in your own terminal. If the Test tab tells you to authorize an application first, grant a machine-to-machine application on the **application access** tab and reload.

## Resource indicators and tokens

Each access token the platform issues for an API carries that API's identifier as its **audience**, so the resource can verify the token was meant for it. Applications select which API they want a token for using the resource indicator, which lets one application hold separate, audience-scoped tokens for several APIs.

On the API's settings tab you control how those tokens are shaped:

- **Signing algorithm**: the asymmetric algorithm (RS256, RS384, RS512, or PS256) used to sign the tokens. Pick **PS256** for an API that is called by an application using a [Financial-grade API security profile](https://dts-identity.com/docs/integrations/applications.md#financial-grade-api-security): that profile signs the application's own tokens with PS256 and advises against RS256. This setting is independent of the profile, so it has to be changed here as well.
- **Access token lifetime**: how long a token is valid (defaults to one day).
- **Implicit access token lifetime**: a shorter lifetime applied to tokens issued through browser-based implicit flows (defaults to two hours).

## One API or many?

An access token always carries exactly **one audience**. Multi-audience tokens are not issued: a token minted for one API is not accepted by another (see [The API as a verifiable contract](#the-api-as-a-verifiable-contract)). If your backend is a set of microservices, this leaves a design decision:

**One logical API for one trust domain.** Register a single API whose identifier stands for the whole backend (for example `https://api.example.com`) and give each service its own scope namespace (`orders.read`, `inventory.write`, and so on). Every service validates the same audience and enforces only its own scopes; the client holds one token for the whole backend, and a new service joins by adding scopes instead of a new registration. Choose this when the services are built and operated together, typically behind one gateway. Be aware of the trade-off: within the shared audience the services no longer isolate each other through the audience check (any of them accepts a token that was sent to a sibling service), only through scopes.

**One API per trust boundary.** Register separate APIs when the resources have different trust levels or owners, or when third parties are involved. A client then requests a separate token per API through the resource indicator (see [Resource indicators and tokens](#resource-indicators-and-tokens)), and a backend service can swap a token it already holds through [token exchange](#token-exchange). Across the boundary the audience check stays meaningful: a token captured at one API is worthless at the other.

Mixing both is common: one logical API for the cohesive core, separate APIs for the parts that need stronger isolation.

**How far to pass a user's token along.** Treat the user's access token as a credential, not as request context. Forward it at most one hop deep, from the client to your API edge (the gateway or first service). Services deeper in a call chain should either sit behind the logical API's shared audience or receive a narrower token minted through token exchange; every additional hop the original token travels widens where a leaked token can be replayed.

## Token exchange

The token endpoint supports **OAuth 2.0 Token Exchange** (RFC 8693) so that a service can call a downstream API on a signed-in user's behalf without passing the original token along: the application swaps a user access token it already holds for a new, narrower token targeting another API.

The grant is deliberately limited to **downscoping**:

- Only a **web** application (confidential) can use it, and only when **Token exchange** is enabled among its grant types (see [Applications](https://dts-identity.com/docs/integrations/applications.md)).
- The subject token must be a still-valid **user access token issued to the same application** that performs the exchange. Exchanging another application's tokens, tokens without a user, or delegation with an `actor_token` is not supported.
- The request names **exactly one target API** through `resource`. The target API's [user-delegated access policy](#user-delegated-access) applies to the exchanging application like on any other token request.
- The issued token is **never broader than the subject token**: its scopes are the intersection of the requested scopes, the subject token's scopes, the target API's scopes, and what the user is entitled to.
- The new token stays bound to the same user and session and follows the target API's token lifetime settings.

Example request against the token endpoint (the application authenticates as usual, for example with its client secret):

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.read
```

The response carries the new `access_token` together with `expires_in` and the effectively granted `scope`.

## Scopes vs. permissions

Defining a scope on an API only makes it *requestable*. It does not grant anyone access to it. What actually lands in a token is decided separately:

- **For machine-to-machine tokens**, the token carries exactly the scopes the application's client grant authorizes (see [Granting an application](#granting-an-application)). A machine client has no user and no roles, so **assigning a role to a machine-to-machine application has no effect**. Its scopes come only from the grant.
- **For user-bearing tokens** (issued when an interactive app requests a token on a signed-in user's behalf), [role-based access control](#role-based-access-control) decides which scopes the user is entitled to. The scopes that end up in the token are the **intersection** of what the application requested and what the user is entitled to.

This is the usual answer to *"why is the scope I requested silently missing from my token?"*: the scope was requested but the caller was not entitled to it, so it was dropped rather than refused.

> **Defense in depth:** a scope present in a token is a *grant*, not a guarantee. Your API should still enforce its own object-level checks (does *this* user own *this* record?). A valid token with a broad scope is not a substitute for authorization on the resource itself.

## Role-based access control

> **Plan note:** Role-based access control is available on the Advanced plan and above (and on Trial).

A custom API can opt into RBAC, which lets the platform embed a user's roles and permissions directly into the tokens it issues for that API. On the API settings tab:

- **Include roles and permissions (RBAC)** turns it on for the API.
- **Include permissions claim** includes the user's granted scopes for this API as a `permissions` claim.
- **Include roles claim** includes the user's role names as a `roles` claim.

These claims are added only to **user-bearing** tokens. The application then makes authorization decisions from those claims. To define roles and assign them to users and groups, see [Roles](https://dts-identity.com/docs/integrations/roles.md).

The **access token** is where those decisions belong. A `roles` claim also reaches the ID token when an application requests the `roles` scope, but that one is for presentation only, see [Enforce on the access token, not the ID token](https://dts-identity.com/docs/integrations/roles.md#enforce-on-the-access-token-not-the-id-token).

## The API as a verifiable contract

A registered API is, in effect, a contract between you and the resource server:

- Its **identifier** is stable and becomes the **audience** of every token issued for it.
- The platform **signs** each token with its signing key (see [Signing keys](https://dts-identity.com/docs/settings/signing-keys.md)).
- The resource server validates the token before trusting any scope: it checks the **signature**, that the **issuer** is this platform, and that the **audience** matches its own identifier, then reads the scopes.

If any of those fail, the resource server should reject the request outright.

## Call the management API (machine-to-machine quickstart)

To let a script or backend service call the platform's own management API:

1. Create a **machine-to-machine** application (see [Applications](https://dts-identity.com/docs/integrations/applications.md)).
2. On the **System API**'s application-access tab, grant that application the management scopes it needs (for example `users.read`, `groups.write`). Grant only the scopes the integration actually uses.
3. From your service, request a token with the **client-credentials** grant against the token endpoint, using the System API's identifier as the **audience**.
4. Call the management endpoints under `/api/v1/...` with the returned token in the `Authorization: Bearer` header.

The **Test** tab on the System API generates exactly these two commands for you, pre-filled with a real application. Copy them as a starting point.

A token stops working before it expires as soon as the application loses its access on the System API, its client secret is rotated or the application is deleted. The service then gets `HTTP 401` and has to request a new token.

## Machine-to-machine token limits

Two limits apply to tokens issued through the client-credentials grant. Both are shown on the **Integrations → APIs** overview. Tokens for interactive user logins are never affected by either.

**Token requests per minute, per client**: the throughput limit. Requests beyond it are answered with `HTTP 429` and a `Retry-After` header; the client can retry once the header's delay has passed.

| Plan | Token requests per minute |
|---|---|
| Trial | 30 |
| Free | 60 |
| Essential | 1,200 |
| Advanced | 6,000 |
| Pro | 30,000 |

**Tokens per month, tenant-wide**: a volume budget that exists on the entry plans only. It covers all machine-to-machine applications and all APIs together and resets on the 1st of each month. Once it is spent, further client-credentials requests are answered with `access_denied` until the next month begins.

| Plan | Tokens per month |
|---|---|
| Trial / Free | 1,000 |
| Essential and above | Unlimited |

A client that caches its access token for the token's full lifetime needs roughly 720 tokens per month and stays far below both limits, so either one is normally reached only by a client that requests a fresh token for every single API call. Cache the token in the calling service and reuse it until shortly before it expires; the token lifetime is configured per API on the API's settings tab.

## Developer / API reference

The platform ships interactive, in-product API documentation at **/admin/api-docs**. It lists every management endpoint with its parameters and lets you try calls in the browser, and you can download the machine-readable OpenAPI definition from the same page.

The management API covers user, group, organization, application, role, log, and device administration. Use **/admin/api-docs** as the authoritative endpoint reference rather than a static list here.

## Reference

| Term | Meaning |
|---|---|
| Identifier (audience) | The value identifying the API; appears in tokens issued for it. |
| Scope / permission | A single capability a token can carry. |
| User policy | Whether interactive applications may obtain tokens on a user's behalf. |
| Client policy | Whether applications may obtain tokens for themselves (machine-to-machine). |
| Grant | An explicit authorization of one application to call this API with specific scopes. |
| RBAC | Embedding a user's roles and permissions into the API's tokens. |
| Token exchange | Swapping a user access token for a narrower token that targets another API (RFC 8693). |

## Troubleshooting

- **The token request is rejected with an invalid scope.** An application can only request scopes it has been granted on the API. Add the scope to the application's grant for this API, then request a fresh token.
- **Calls return an insufficient-scope error even though a token was issued.** A request succeeds only if the token actually carries the scope the endpoint requires. Decode the token and confirm the granted scopes include it; scopes the application was not granted are silently dropped from the token.
- **The token has the wrong audience.** The token must be requested for this API's identifier (audience). A token minted for a different API, or with no audience, is not accepted here.
- **The token test returns nothing or an error.** The test issues a token for the selected application and scopes. Make sure the application has an active grant on this API and that at least one scope is selected.
- **A token exchange is rejected.** The subject token must be a still-valid, user-bearing access token issued to the same application that performs the exchange, the application must have the token-exchange grant enabled, and the request must name exactly one target API through `resource`. Machine-to-machine tokens (no user) cannot be exchanged.

See also the [glossary](https://dts-identity.com/docs/reference/glossary.md).
