Skip to content

API Access

API-Access is an alternative token endpoint of the SSO that simplifies getting valid tokens for REST or Web APIs without having to ask for Token Exchange permissions. You can get a valid token for any other application by making a Client Credentials Grant request with a valid Client ID and Client Secret. You can do that by including an audience field in the request.

The roles inside the token are the ones assigned to the Application Identity that got the token, defined in the target application.

Registering an API Client

  1. Create a new application in the Applications Portal.
  2. Add a new SSO Registration.
  3. Select OIDC and use the same options as in the image below.

register client credentials

Getting an API Access Token

The token endpoint URL is:

https://auth.cern.ch/auth/realms/cern/api-access/token

To get an access token, perform a standard client credentials grant request to that endpoint with an extra form parameter audience=<target_application>. The simplest example to get a token using cURL would be:

curl --location --request POST "https://auth.cern.ch/auth/realms/cern/api-access/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=my-client-id" \
--data-urlencode "client_secret=00000000-0000-0000-0000-000000000000" \
--data-urlencode "audience=the-target-api"

Info

The sub (subject) claim of the token will be in the format service-account-<client id>. Don't be confused by the name "service account", this is not a CERN service account, it's an account that only exists in the context of application credentials. It should be accepted by the target API in this context.

Then include this token as a Bearer Token in your HTTP requests to the target API.

You can browse more examples in our GitLab repository.

Accepting an API Access Token

If you are an API developer, we recommend accepting tokens issued by the SSO that include your Client ID in the aud claim. Role Based Permissions will work as usual: in this case, you will have to give permissions by adding the applications of your choice (those who will get API Access tokens) to the groups assigned to your roles.

Usage for the Authorization Service API

With this token you will be able to call the Authorization Service API. You may need to Request Additional Permissions for your application for some endpoints.