Docs

Authentication for organization APIs

# Authentication for organization APIs

To access the management APIs of organizations in Asgardeo, you must first get an access token from your organization for the API operations you want to execute. You can then use this access token to invoke those API operations securely.

The following is a high-level diagram of how to authenticate to organization APIs.

Get access to for organization APIs

Follow the steps given below to get an access token with the required permissions.

  1. Register a management app
  2. Request for authorization code
  3. Request an access token against the root organization
  4. Request an access token against the organization

# Register a management app

Use the standard-based app type to register an OIDC management app:

  1. On the Asgardeo Console, go to Applications.

  2. Click New Application and select Standard-Based Application to open the following:

    Register a standard based application

  3. Provide an application name.

  4. Select OIDC Standard-Based Application as the app type and then select the Management Application checkbox.

    Learn more about OIDC configurations.

  5. Click Register to complete the registration.

  6. Click Share Application to share the application with organizations.

  7. Go to the Protocol tab and select Authorization Code and Organization Switch as the grant types for the application.

"Important"

Select Client Credentials grant if the APIs you intend to access do not require the use of the internal_login scope. The Authorization Code grant is specifically designed for APIs that rely on the internal_login scope, making it the appropriate choice in such cases.

The client credentials for your application are displayed in the protocol tab, as shown below. Obtain the client ID and client secret of the app

The client ID and client secret are sensitive information that must be protected. See the best practices before you proceed.

# Get the authorization code

"Important"

If you are using the Client Credentials grant in your application, you can skip this step and directly obtain the required access tokens using the client credentials request.

First, your app must initiate a login request to the authorization endpoint of Asgardeo. After redirecting to Asgardeo, the user should be prompted with a login page if the user is not authenticated.

Request Format

https://api.asgardeo.io/t/<root_organization_name>/oauth2/authorize?response_type=code&redirect_uri={redirect_uri}&client_id={client_id}
1
Request Parameter Description
response_typeRequired Required grant type. Use code to represent the authorization code grant type.
redirect_uriRequired 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.
client_idRequired The client ID obtained when registering the application in Asgardeo.

# Get access tokens

In this flow, the application needs to get tokens for the root organization and exchange the obtained token to get an access token for the organization.

Let's see how this works:

# Step 1: For the root organization

After receiving the authorization code, the application has to exchange it to get the tokens given below:

  • access_token
  • id_token

The application has to provide its credentials and get the tokens.

  • Token request for Authorization code grant

    curl --location --request POST 'https://api.asgardeo.io/t/<root_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>'
    1
    2
    3
    4
    5
    6
    7

    This token request has the following parameters:

    Request Parameter Description
    codeRequired The authorization code received from the authorization request.
    grant_typeRequired The grant type. Here we are using the authorization_code grant.
    redirect_uriRequired This is where the response is redirected to at the end of the process.

  • Token request for Client Credentials grant

    Use the following cURL command format in your request:

    curl -X POST https://api.asgardeo.io/t/<root_org_name>/oauth2/token \
-u  '<client_id>:<client_secret>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=<scope>'
    1
    2
    3
    4

    Replace the following variables in the above request.

    Variable Description
    root_org_name Name of your organization on Asgardeo.
    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.
    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.

# Step 2: For the organization

You can now request an access token from the token endpoint by exchanging the access token of the root organization and specifying the internal scopes (permission level) you require to access.

See the relevant API reference docs for the list of internal scopes for each API.

Use the following cURL command format in your request:

curl -X POST \
'https://api.asgardeo.io/t/<root_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>'
1
2
3
4
5
6
7
8

Replace the following variables in the above request.

Variable Description
org_nameRequired Name of your organization on Asgardeo.
client_idRequired Client ID of your application. This is generated when registering the application in Asgardeo.
client_secretRequired Client secret of your application. This is generated when registering the application in Asgardeo.
tokenRequired The access token obtained for the root organization.
scopeRequired 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_organizationRequired The ID of the organization you are switching to.

# Best practices

When invoking the management APIs, we recommend the following best practices:

  • If the client_id and client_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, be 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.
© 2024 WSO2 LLC.