API resources
API resources, a.k.a. Resource Indicators, indicate the target services or resources to be requested, usually, a URI format variable representing the resource's identity. This is a key concept in the Logto authorization system, as it defines the endpoint the authorization policy is designed to protect.
Resource indicator
- A resource value indicates the target service or resource to which access is being requested.
- Its value MUST be an absolute URI.
- The URI MUST NOT include a fragment component.
- It SHOULD NOT include a query component.
- You SHOULD provide the most specific URI it can for the complete API or set of resources it intends to access.
In practice, a client may know a base URI or the application or resource to interact with. It would be appropriate to use it as the value of the resource parameter.
E.g., Logto Management API base URI.
https://tenantId.logto.app/api
By default, this API resource is pre-registered to your Logto service. All the Management APIs under this URI are protected by Logto.
Logto API resource schema
| Property name | Property description | Required |
|---|---|---|
| API Name | A user friendly name that can help you to identify the API resource. | true |
| API Identifier | The unique API Resource Indicator value, with restrictions listed above. | |
| Logto will use it to identify the requested API resource and grant the authorization tokens accordingly. | true | |
| Token expiration time (in seconds) | The expiration time set for access token. The default expiration value is 3600. | false |
| Default API | Only zero or one default API can be set per tenant. | |
| When a default API is designated, the resource parameter can be omitted in the auth request. Subsequent token exchanges will use that API as the audience by default, resulting in the issuance of JWTs. | false |
Requests with a expired access token should be restricted. This is implemented to protect your API from a abused token. The larger value is set, the longer will a issued access token survive, and the more vulnerable your API will be.
Default API
This feature is mainly intended for applications that does NOT support OIDC resource indicators, E.g., ChatGPT plugins.
Logto leverages RFC 8707: Resource Indicators for OAuth 2.0 to implement role-based access control (RBAC). While it is one of the features of OAuth 2.0, it is not yet widely supported.
In Logto's implementation, every user-defined permission (scope) must be associated with an API Resource. Otherwise, it will be treated as an OpenID Connect (or OAuth) permission. Generally, this doesn't affect your authorization process. However, when integrating with third-party apps that lack support for RFC 8707 (e.g., ChatGPT plugins), it can pose challenges since the initial authorization request may not include a resource parameter. Consequently, Logto will always issue Opaque Access Tokens.
To address this issue, you can designate an API Resource as the tenant-level default resource. Once it is done:
- Logto will use the default API Resource when no
resourceparameter is present in the Authentication Request. - If the
openidscope is included, an Opaque Access Token for the Userinfo Endpoint will be issued when noresourceparameter is present in subsequent Token Requests. - If the
openidscope is not included, a JWT Access Token for the default API Resource will be issued when noresourceparameter is present in subsequent Token Requests.
By designating a default API Resource, you can ensure smooth integration with apps lacking RFC 8707 support while maintaining the appropriate access controls.
Register the API resources in Logto
To obtain an audience-restricted access token from Logto, first, register your backend APIs to enable Logto’s audience-restricted access tokens. When an authorization request is received, Logto will identify the registered API resources and grant access accordingly.
To register your APIs, navigate to Console > API resources You will see a built-in resource with the API identifier displayed as https://[your-tenant-id].logto.app/api. This resource encompasses all the Management APIs of Logto and ensures that they are protected and accessible only to authorized users of Logto.
Click on the Create API resource button and follow the interactive form to create your own API resources:
- A human-readable API name that may better help you to identify this entity.
- A unique API identifier in URI format. It represents the identity of the API resource.
The new API will show up on the list once created. You may manage or delete it at the API details page by clicking on the entity.