Several national APIs require access tokens with the API Resource as the only audience. This may be done by making a request to the authorize endpoint (and a corresponding request to the token endpoint) for each API a client need access to.

This technique is cumbersome and may degrade the user experience as the browser is redirected to HelseID for each request to the authorize endpoint.

As an alternative, we support the resource indicator specification - RFC 8707.

Our public github repository has sample code showing use of the resource parameter.

How to request multiple API resources

Consider these APIs which both require access tokens with single audiences.

API 1

API-name (audience):

owner-1:api

Scopes:

owner-1:api\read

owner-1:api\write

API 2

API-name (audience):

owner-2:api

Scopes:

owner-2:api\read

Authenticating the user and indicating resources

The client must

• Indicate which API resources will be requested (the resource parameter)

• Indicate which scopes will be requested for the API resources (the scope parameter)

• Require refresh token (the offline scope in the scope parameter)

GET /authorize?
client_id=client&
response_type=code&
scope=owner-1:api\write owner-2:api\read offline_access&
resource=owner-1:api&
resource=owner-2:api
....

Requesting the first access token

You then redeem the code returned from the authorize endpoint, and specify for which resource you want an access token (resource=owner-1:api).

POST /token

grant_type=authorization_code&
client_id=client&
client_assertion=...&
client_assertion_type=..&
authorization_code=...&
redirect_uri=...&
resource=owner-1:api 
....

Requesting the next access token

The previous request will return a refresh token and an access token with audience owner-1:api and scope owner-1:api\write. You use the refresh token to aquire the next access token.

POST /token

grant_type=refresh_token&
client_id=client&
client_assertion=...&
client_assertion_type=..&
refresh_token=...&
resource=owner-2:api
....

This will return a new refresh token and an access token with audience owner-2:api and scope owner-2:api\readDokumentet har blitt flyttet til Utviklerportalen.

This document has been moved. Please see the document at this page (English).