openapi: 3.0.1 info: title: Logto API references Account center Resources API description: 'API references for Logto services. Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.' version: Cloud servers: - url: https://[tenant_id].logto.app/ description: Logto endpoint address. security: - OAuth2: - all tags: - name: Resources description: 'Resources (API resources) represent the APIs that you want to protect with Logto. Each resource has a unique indicator (URI) and a set of scopes (permissions). The resources will be used in the authorization process which conforms to [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html). See [⚔️ Protect your API](https://docs.logto.io/docs/recipes/protect-your-api/) to learn more about how to define API resources and protect your APIs with Logto.' paths: /api/resources: get: operationId: ListResources tags: - Resources parameters: - name: includeScopes in: query required: false schema: type: string description: If it's provided with a truthy value (`true`, `1`, `yes`), the scopes of each resource will be included in the response. - name: page in: query description: Page number (starts from 1). required: false schema: type: integer minimum: 1 default: 1 - name: page_size in: query description: Entries per page. required: false schema: type: integer minimum: 1 default: 20 responses: '200': description: An array of resources. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - indicator - isDefault - accessTokenTtl properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 isDefault: type: boolean accessTokenTtl: type: number scopes: type: array items: type: object required: - tenantId - id - resourceId - name - description - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 resourceId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Get API resources description: Get API resources in the current tenant with pagination. post: operationId: CreateResource tags: - Resources parameters: [] requestBody: required: true content: application/json: schema: type: object required: - name - indicator properties: tenantId: type: string maxLength: 21 name: type: string minLength: 1 description: The name of the resource. indicator: type: string minLength: 1 description: The unique resource indicator. Should be a valid URI. accessTokenTtl: type: number description: The access token TTL in seconds. It affects the `exp` claim of the access token granted for this resource. default: 3600 responses: '201': description: The created resource. content: application/json: schema: type: object required: - tenantId - id - name - indicator - isDefault - accessTokenTtl properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 isDefault: type: boolean accessTokenTtl: type: number scopes: type: array items: type: object required: - tenantId - id - resourceId - name - description - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 resourceId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Content summary: Create an API resource description: Create an API resource in the current tenant. /api/resources/{id}: get: operationId: GetResource tags: - Resources parameters: - $ref: '#/components/parameters/resourceId-root' responses: '200': description: The requested resource. content: application/json: schema: type: object required: - tenantId - id - name - indicator - isDefault - accessTokenTtl properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 isDefault: type: boolean accessTokenTtl: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get API resource description: Get an API resource details by ID. patch: operationId: UpdateResource tags: - Resources parameters: - $ref: '#/components/parameters/resourceId-root' requestBody: required: true content: application/json: schema: type: object properties: tenantId: type: string maxLength: 21 name: type: string minLength: 1 description: The updated name of the resource. accessTokenTtl: type: number description: The updated access token TTL in seconds. responses: '200': description: The updated resource. content: application/json: schema: type: object required: - tenantId - id - name - indicator - isDefault - accessTokenTtl properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 isDefault: type: boolean accessTokenTtl: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Update API resource description: Update an API resource details by ID with the given data. This method performs a partial update. delete: operationId: DeleteResource tags: - Resources parameters: - $ref: '#/components/parameters/resourceId-root' responses: '204': description: The resource was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete API resource description: Delete an API resource by ID. /api/resources/{id}/is-default: patch: operationId: UpdateResourceIsDefault tags: - Resources parameters: - $ref: '#/components/parameters/resourceId-root' requestBody: required: true content: application/json: schema: type: object required: - isDefault properties: isDefault: type: boolean description: The updated value of the `isDefault` property. responses: '200': description: The updated resource. content: application/json: schema: type: object required: - tenantId - id - name - indicator - isDefault - accessTokenTtl properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 indicator: type: string minLength: 1 isDefault: type: boolean accessTokenTtl: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Set API resource as default description: 'Set an API resource as the default resource for the current tenant. Each tenant can have only one default API resource. If an API resource is set as default, the previously set default API resource will be set as non-default. See [this section](https://docs.logto.io/docs/references/resources/#default-api) for more information.' /api/resources/{resourceId}/scopes: get: operationId: ListResourceScopes tags: - Resources parameters: - $ref: '#/components/parameters/resourceId' - name: page in: query description: Page number (starts from 1). required: false schema: type: integer minimum: 1 default: 1 - name: page_size in: query description: Entries per page. required: false schema: type: integer minimum: 1 default: 20 - name: search_params in: query description: Search query parameters. required: false schema: type: object additionalProperties: type: string explode: true responses: '200': description: An array of scopes for the requested resource. content: application/json: schema: type: array items: type: object required: - tenantId - id - resourceId - name - description - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 resourceId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Get API resource scopes description: Get scopes (permissions) defined for an API resource. post: operationId: CreateResourceScope tags: - Resources parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 256 description: The name of the scope. It should be unique for the resource. description: type: string nullable: true responses: '201': description: The created scope. content: application/json: schema: type: object required: - tenantId - id - resourceId - name - description - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 resourceId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Create API resource scope description: Create a new scope (permission) for an API resource. /api/resources/{resourceId}/scopes/{scopeId}: patch: operationId: UpdateResourceScope tags: - Resources parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/scopeId' requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 256 description: The updated name of the scope. It should be unique for the resource. description: type: string nullable: true responses: '200': description: The updated scope. content: application/json: schema: type: object required: - tenantId - id - resourceId - name - description - createdAt properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 resourceId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: type: string nullable: true createdAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Update API resource scope description: Update an API resource scope (permission) for the given resource. This method performs a partial update. delete: operationId: DeleteResourceScope tags: - Resources parameters: - $ref: '#/components/parameters/resourceId' - $ref: '#/components/parameters/scopeId' responses: '204': description: The scope was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete API resource scope description: Delete an API resource scope (permission) from the given resource. components: parameters: resourceId: in: path description: The unique identifier of the resource. required: true schema: type: string name: resourceId resourceId-root: in: path description: The unique identifier of the resource. required: true schema: type: string name: id scopeId: in: path description: The unique identifier of the scope. required: true schema: type: string name: scopeId securitySchemes: OAuth2: type: oauth2 description: "Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).\n\n### Get started\n\nThe API follows the same authentication principles as other API resources in Logto, with some slight differences. To use Logto Management API:\n\n1. A machine-to-machine (M2M) application needs to be created.\n2. A machine-to-machine (M2M) role with Management API permission `all` needs to be assigned to the application.\n\nOnce you have them set up, you can use the `client_credentials` grant type to fetch an access token and use it to authenticate your requests to the Logto Management API.\n\n### Fetch an access token\n\nTo fetch an access token, you need to make a `POST` request to the `/oidc/token` endpoint of your Logto tenant.\n\nFor Logto Cloud users, the base URL is your Logto endpoint, i.e. `https://[tenant-id].logto.app`. The tenant ID can be found in the following places:\n\n- The first path segment of the URL when you are signed in to Logto Cloud. For example, if the URL is `https://cloud.logto.io/foo/get-started`, the tenant ID is `foo`.\n- In the \"Settings\" tab of Logto Cloud.\n\nThe request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:\n\n```bash\ncurl --location \\\n --request POST 'https://[tenant-id].logto.app/oidc/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=[app-id]' \\\n --data-urlencode 'client_secret=[app-secret]' \\\n --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\\n --data-urlencode 'scope=all'\n```\n\nReplace `[tenant-id]`, `[app-id]`, and `[app-secret]` with your Logto tenant ID, application ID, and application secret, respectively.\n\nThe response will be like:\n\n```json\n{\n \"access_token\": \"eyJhbG...2g\", // Use this value for accessing the Logto Management API\n \"expires_in\": 3600, // Token expiration in seconds\n \"token_type\": \"Bearer\", // Token type for your request when using the access token\n \"scope\": \"all\" // Scope `all` for Logto Management API\n}\n```\n\n### Use the access token\n\nOnce you have the access token, you can use it to authenticate your requests to the Logto Management API. The access token should be included in the `Authorization` header of your requests with the `Bearer` authentication scheme.\n\nHere is an example of how to list the first page of users in your Logto tenant:\n\n```bash\ncurl --location \\\n --request GET 'https://[tenant-id].logto.app/api/users' \\\n --header 'Authorization: Bearer eyJhbG...2g'\n```\n\nReplace `[tenant-id]` with your Logto tenant ID and `eyJhbG...2g` with the access token you fetched earlier." flows: clientCredentials: tokenUrl: /oidc/token scopes: all: All scopes