Resources in your tenant

Register a resource

1. Open OAuth Management, Resources and select Create resource.
2. Enter the resource identifier: the absolute URI clients will send, such as https://api.example.com/photos. Use https, or http on 127.0.0.1, [::1] or localhost for an API on the same computer. A fragment is not allowed. The identifier stays fixed after creation.
3. Enter a name. The consent page shows it next to the requested scopes, so people know which service the access is for.
4. Optionally set an audience, the aud value its tokens carry. Leave it empty to use the identifier, which is what most APIs check. An enabled resource's audience and identifier must differ from every other enabled resource's, and from the tenant address followed by /resource, so a token for one API is never accepted by another.
5. List the scopes that belong to this API, and choose its access token manager, then save.

A tenant can register 50 resources. Each one records who created it.

The resource parameter

A client names the API it wants a token for with the resource parameter (RFC 8707) at the authorization endpoint, the token endpoint, or both. It is the only parameter that may appear more than once. The value must match a registered, enabled identifier exactly: https://api.example.com/photos/ with a trailing slash is a different string. Anything else is refused with invalid_target, and the tenant's protocol Audit records the specific reason, such as unknown_resource or resource_not_allowed.

A resource named in the authorization request applies to the whole grant: the code, and the refresh token issued from it, may be used only for those resources. Each token request may then name some of them and receives a token for just those. With no resource at the token endpoint, the token is for every resource the authorization named. A client can be limited to some resources in Clients, under Allowed resources; leaving the list empty allows any enabled resource.

The token's aud is the named resource's audience, or a list of audiences when several are named. A resource the client named always decides aud, whatever its access token manager configures.

Scopes and resources

A scope belongs to at most one resource. When a client names resources, every scope it asks for must belong to one of them or to no resource; a scope that belongs to another API is refused with invalid_target, the RFC 8707 error for a resource and scope that do not go together (reason scope_not_for_resource). When a later token request names only some of the authorized resources, the token carries only their scopes and the scopes that belong to no resource, while the refresh token keeps them all. Built-in scopes such as openid and offline_access belong to no resource. The same rule applies when a request names no resource and the token is addressed to the default resource: a scope that belongs to another API needs that API named. Only a token addressed to no registered resource, the tenant address followed by /resource, carries any scope.

Managers and audiences

Each resource can choose the access token manager for tokens addressed to it, for example opaque tokens with a short lifetime for a sensitive API. Leave it on the client's own access token manager to keep each client's settings. Resources with different managers cannot share one token, so naming two of them in one request is refused with invalid_target (reason resources_incompatible); request a token for each.

Default and required

In Flow Policy, Resource parameter chooses what happens when a request names no resource. By default the token is addressed to the default resource, or to the tenant address followed by /resource when none is chosen. In that case the access token manager may still set its own aud. Choosing Refuse the request makes every client name its API, and requests without one receive invalid_target (reason resource_required). The default resource cannot be deleted or turned off while it is the default.

Linked resource servers

A confidential client with resource server introspection turned on can introspect access tokens issued to other clients, which is how an API checks opaque tokens. Linking it to resources under Linked resource servers chooses which: it then sees only tokens whose aud includes one of its resources, and any other token reads as inactive. A resource server linked to nothing sees only tokens addressed to no registered resource, such as those whose aud is the tenant address followed by /resource; a token for a registered resource, including the default resource, reads as inactive to it, so one API cannot read the tokens meant for another.

Protected resource metadata

For a resource identified on the tenant's own host, the tenant publishes protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource followed by the identifier's path. For https://<tenant host>/lab-api/photos it is https://<tenant host>/.well-known/oauth-protected-resource/lab-api/photos. The document lists the resource identifier, this tenant as its authorization server, the resource's scopes, bearer_methods_supported, its name and, when set, the documentation link. Identifiers on other hosts cannot be described from the tenant's host, so their API publishes its own. Turn off Publish protected resource metadata to stop publishing it. Clients may cache it for five minutes.

Permissions, history and limits

Reading, creating, updating and deleting resources each need their own tenant permission, which Tenant Admin holds. Every change, and every refused attempt, is recorded in the tenant's Audit under OAuth management. Changing a resource's audience, scopes, access token manager or enabled status revokes tokens, pending codes and remembered consent addressed to it; a new name, description, documentation link, metadata setting or linked resource server revokes nothing. The editor warns before a save that revokes. The resource count appears in the tenant's usage view.