Skip to content

docs: add token guide for org api resource #639

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/docs/recipes/organizations/integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -320,3 +320,23 @@ In your API, you can verify the organization token which is similar to [Proctect
- Unlike access tokens for API resources, a user CANNOT get an organization token if the user is not a member of the organization.
- The audience of the organization token is `urn:logto:organization:{organization_id}`.
- For certain permissions (scopes), you need to check the `scope` claim of the organization token by splitting the string with space as delimiter.

## Fetch organization-scoped access token for an API resource

In addition to orgnization scopes, organization role can be also assgined with API resource scopes. By default, like RBAC roles, all the scopes inherited from the organization role will be included in the access token.

You may want to narrow down the scopes to specific organization's roles, for example, to access an API resource that is only available to the organization. You can add `organization_id` to the token request, if you are using Logto's SDK, you can add `organization_id` as the second parameter of the `getAccessToken` method.

```ts
// Use JavaScript as an example
const accessToken = await logto.getAccessToken('https://my-resource.com/api', 'org_1');

// Or getting claims directly
const accessTokenClaims = await logto.getAccessTokenClaims('https://my-resource.com/api', 'org_1');
console.log(accessTokenClaims.organization_id); // 'org_1'
console.log(accessTokenClaims.aud); // 'https://my-resource.com/api'
```

Then only the scopes inherited from this organization's roles will be included in the access token. And an additional claim `organization_id` will be included in the access token, this is helpful to identify the organization the user is acting on behalf of.

And the recommended way to verify the access token is to check both the `scope` and `organization_id` claims.
Loading