Skip to content

Commit cdf847e

Browse files
authored
docs: add token guide for org api resource (#639)
1 parent 7b1b7e0 commit cdf847e

File tree

1 file changed

+20
-0
lines changed

1 file changed

+20
-0
lines changed

docs/docs/recipes/organizations/integration.mdx

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,3 +320,23 @@ In your API, you can verify the organization token which is similar to [Proctect
320320
- Unlike access tokens for API resources, a user CANNOT get an organization token if the user is not a member of the organization.
321321
- The audience of the organization token is `urn:logto:organization:{organization_id}`.
322322
- For certain permissions (scopes), you need to check the `scope` claim of the organization token by splitting the string with space as delimiter.
323+
324+
## Fetch organization-scoped access token for an API resource
325+
326+
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.
327+
328+
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.
329+
330+
```ts
331+
// Use JavaScript as an example
332+
const accessToken = await logto.getAccessToken('https://my-resource.com/api', 'org_1');
333+
334+
// Or getting claims directly
335+
const accessTokenClaims = await logto.getAccessTokenClaims('https://my-resource.com/api', 'org_1');
336+
console.log(accessTokenClaims.organization_id); // 'org_1'
337+
console.log(accessTokenClaims.aud); // 'https://my-resource.com/api'
338+
```
339+
340+
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.
341+
342+
And the recommended way to verify the access token is to check both the `scope` and `organization_id` claims.

0 commit comments

Comments
 (0)