Access organization APIs¶
To access organization APIs in Asgardeo, you must first get an access token. Follow the steps given below to get an access token with the required permissions.
Step 1: Register an OIDC application¶
Follow the steps below to register an application:
-
On the Asgardeo Console, go to Applications.
-
Click New Application and select Standard-Based Application to open the following:
-
Provide an application name.
-
Select OAuth 2.0 OpenID Connect as the application protocol.
-
Click Register to complete the registration.
-
Click Share Application to share the application with organizations.
-
Go to the Protocol tab and,
-
select Authorization Code and Organization Switch as the grant types for the application.
-
configure authorized redirect URLs for your application.
Note
Learn more about OIDC configurations.
-
-
Take note of the client credentials displayed in the Protocol tab.
Step 2: Authorize the application to consume API resources¶
Applications must be provided with the relevant permissions to consume API resources. To authorize the application,
-
On the Asgardeo Console, go to Applications.
-
Select the created application and go to its API Authorization tab.
-
Click Authorize an API Resource and provide the relevant details of the API resource along with the scopes. Repeat the step for the required APIs.
Tip
Find the relevant scopes from the API definition of organization APIs.
-
Click Finish to save the changes.
Note
For more information, refer to API authorization.
Step 3: Create roles and associate them with the application¶
Depending on the role audience of the application, applications may be associated with roles made for the entire organization or tailored specifically for the application. Follow the steps below to create a role and associate it with the application.
-
Create an application role or an organization role that authorizes organization APIs. Learn how to do so in manage roles.
-
Go to the Roles tab of the created application.
-
Depending on where you created the role, do one of the following:
- If you created an application role, select Role Audience as Application and under Assigned Roles, select the created role.
- If you created an organization role, select Role Audience as Organization to associate all organization-level roles including the created role.
-
Click Update to save the changes.
Step 4: Share the application with organizations¶
The application should be shared with organizations in order for the associated roles to be available in the organization.
Follow the guide to share applications with organizations.
Step 5: Assign users to the roles¶
Once an application is shared to an organization, the associated roles will also be shared with the organization. Organization admins can then selectively assign organization users to these roles.
Follow the guide to assign users to roles.
Step 6: Get the authorization code¶
Your application must initiate a login request to the authorization endpoint of Asgardeo. Any user who is not authenticated will be prompted with a login page.
https://api.asgardeo.io/t/{organization_name}/oauth2/authorize?\
response_type=code\
&redirect_uri={redirect_uri}\
&scope={space-separated list of scopes}\
&client_id={client_id}
https://api.asgardeo.io/t/bifrost/oauth2/authorize?\
response_type=code\
&redirect_uri=https://localhost:3000\
&scope=openid internal_org_application_mgt_view\
&client_id=z8RB6ysdDZhe4QO0zJAQzKbi6P4a
Request Parameter | Description |
---|---|
response_type |
Required grant type. Use code to represent the authorization code grant type. |
redirect_uri |
This is where the response is redirected to at the end of the process. This needs to be the same as one of the URLs given in the registered apps. |
scope |
The scope corresponding to the API you want to use. See the relevant API reference docs for the list of internal scopes for each API. |
client_id |
The client ID obtained when registering the application in Asgardeo. |
Step 7: Get access tokens¶
After receiving the authorization code, the application has to exchange it to get the id_token
and the access_token
. The method of obtaining these tokens differs depending on the type of user.
Before you begin
For a user to receive access tokens with the right permissions, the following conditions should be fulfilled with steps 2-5.
-
The application is authorized to consume the requested scopes.
-
The role associated with the application is authorized to consume the requested scopes.
-
The organization user is assigned to the above role authorized to consume the requested scopes.
For a user managed by the organization¶
A user created within the organization may use organization SSO to log in to the application. The access token received in this case can be directly used to access organization APIs.
The access token request is as shown below.
curl --location --request POST 'https://api.asgardeo.io/t/{organization_name}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code={authorization_code}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'redirect_uri={redirect_uri}'
curl --location --request POST 'https://api.asgardeo.io/t/bifrost/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=97c85a59-a758-3a56-95cd-e71a505b493d' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=z8RB6ysdDZhe4QO0zJAQzKbi6P4a' \
--data-urlencode 'client_secret=2mcunRfr56ght72Vf7phNUbQRgeOCmrnVkLJA4wa' \
--data-urlencode 'redirect_uri=https://localhost:3000'
This token request has the following parameters:
Request Parameter | Description |
---|---|
code |
The authorization code received from the authorization request. |
grant_type |
The grant type. Here we are using the authorization_code grant. |
redirect_uri |
This is where the response is redirected to at the end of the process. |
For an invited user managed by the parent organization.¶
If the organization user is an invited user of the parent organization, the user logs into the application using the credentials of the parent organization. The access token obtained in this process cannot be directly used to access organization APIs. It has to be exchanged using the organization switch grant to a token usable within the organization. Let's see how this works:
-
Initiate the token request using the following command.
curl --location --request POST 'https://api.asgardeo.io/t/{organization_name}/oauth2/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'code={authorization_code}' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'client_id={client_id}' \ --data-urlencode 'client_secret={client_secret}' \ --data-urlencode 'redirect_uri={redirect_uri}'
curl --location --request POST 'https://api.asgardeo.io/t/bifrost/oauth2/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'code=97c85a59-a758-3a56-95cd-e71a505b493d' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'client_id=z8RB6ysdDZhe4QO0zJAQzKbi6P4a' \ --data-urlencode 'client_secret=2mcunRfr56ght72Vf7phNUbQRgeOCmrnVkLJA4wa' \ --data-urlencode 'redirect_uri=https://localhost:3000'
This token request has the following parameters:
Request Parameter Description code
The authorization code received from the authorization request. grant_type
The grant type. Here we are using the authorization_code
grant.redirect_uri
This is where the response is redirected to at the end of the process. -
Once the user successfully obtains a token by logging into the parent organization, use the following command to exchange it to a token usable within the organization.
curl -X POST \ 'https://api.asgardeo.io/t/{organization_name}/oauth2/token' \ --header 'Authorization: Basic <base64 Encoded (clientId:clientSecret)>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=organization_switch' \ --data-urlencode 'token={access token from step 1}' \ --data-urlencode 'scope={required scopes}' \ --data-urlencode 'switching_organization={organization id}'
curl -X POST \ 'https://api.asgardeo.io/t/bifrost/oauth2/token' \ --header 'Authorization: Basic ejhSQjZ5c2REWmhlNFFPMHpKQVF6S2JpNlA0YTp6MEM3OXpsb3B4OGk3QnlPdzhLMTVBOWRwbFlh' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=organization_switch' \ --data-urlencode 'token=54bd024f-5080-3db5-9422-785f5d610605' \ --data-urlencode 'scope=openid internal_org_application_mgt_view' \ --data-urlencode 'switching_organization=9e394cbf-70bf-532a-955d-0ef34597f2ef'
This token request has the following parameters:
Variable Description client_id
Client ID of your application. This is generated when registering the application in Asgardeo. client_secret
Client secret of your application. This is generated when registering the application in Asgardeo. token
The access token obtained for the root organization. scope
The scope corresponding to the API you want to use. See the relevant API reference docs for the list of internal scopes for each API. switching_organization
The organization ID of the organization you are switching to.
Step 8: Access the API¶
You can now use the access token to access APIs as follows:
curl -X GET https://api.asgardeo.io/t/{organization_name}/o/api/server/v1/applications \
-H "accept: application/json" \
-H "Authorization: Bearer <access_token>"
Best practices¶
When invoking APIs, we recommend the following best practices:
- If the
client_id
andclient_secret
are compromised, anyone can use them to invoke the client credentials grant and get an access token with all the access levels of the admin. Therefore, we highly recommend not sharing the client id and client secret. - If required, the administrator can set a higher expiry time for the application token through the application configurations in the Asgardeo Console.
- When you request an access token, make sure it is specific to the scopes required for a specific task. This allows you to mitigate the risk of token misuse when you share it with other developers.