Skip to main content

Using IMS Tokens

Access Tokens

Most requests to IMS services or APIs must be authenticated with an Access Token from the OAuth service. Generally, you should attach the Access Token as a Bearer token in the Authorization header of your HTTP requests. Some APIs may have different requirements, for example you might find gRPC services in the IMS stack, and you should check the documentation of the specific IMS service you want to call.

It is possible to verify that an Access Token was issued by the IMS Platform Auth service, and to extract the permissions provided by that token. However, you should not need to do this. The IMS services you send the Access Tokens to will verify and check the permissions themselves, and return a 401 HTTP error code for an expired or invalid token, or a 403 HTTP error code if the token is valid, but the permissions don’t allow for the requested action.

It is best practice for you to rely on the IMS services to tell you the status of the token rather than attempting to parse it yourself. For example, you will know when an Access Token should be refreshed because the services will start to return a 401 HTTP Unauthorized code.

ID Tokens

Some IMS services require an OIDC ID Token instead of an Access Token. This is usually due to downstream requirements, for example GKE requires an OIDC compliant service and ID Token for access. It will be specified in the documentation for the relevant IMS service you need access to whether an ID Token or an Access Token is required. If an ID Token is required it should normally be provided in the same way as an Access Token, that is as a Bearer token in the Authorization header.

As with Access Tokens it is possible for you to parse and verify an ID Token, but you should not need to do this. Let the IMS services handle this for you.

Refresh Tokens

The only use for Refresh Tokens is generating new Access and ID Tokens without requiring users to re-authorize. On authorization, you can request a long-lived Refresh Token. View the Code Samples, or read the OAuth Refresh Token specification, for more information on how to generate or exchange Refresh Tokens.