API Portal

API Portal - Create Application & API subscription & retrieve API keys

This page describes a scenario where you as a consumer logs in to the API Portal, creates an application, generates API keys and adds an API subscription for said application.

Sign In

The API Portal is available in the following environments:

• The production environment
• The verification environment

Create an Application

Read more under API Portal Overview → Applications.

1. Click on 'Applications' in the main menu and then on 'ADD NEW APPLICATION':

   

2. Provide information about the application and click on "SAVE". The new application is now visible under 'Applications'.

   info

   Enter 'Unlimited' as "Shared Quota for Application Tokens". This means that your application has no limits on how many API calls it can make.

   

Generate API-Keys

Read more under API Portal Overview → OAuth2 Tokens.

1. Click on 'Applications' in the main menu and then on the newly created application

2. Click on 'Application Keys' in the left hand menu and then on 'GENERATE KEYS' at the bottom of the page:

   

3. Now your API-Keys are displayed (Consumer Key och Consumer Secret):

   

Add API subscription for access

Read more underAPI Portal Overview → API → Subscriptions & API Portal Overview → Application → Subscriptions.

1. Click the API that the newly created Application should subscribe to and then on the 'Subscriptions' tab:

   
2. Choose the newly created application in the list 'Applications' and also a policy in the list 'Business Plan' that controls the number of calls per minute that is allowed. Lastly click on 'Subscribe'.

API Portal - Terminology

OAuth2 - Recommended Grant Flows

The choice of Grant Flow is usually determined by the type of client and owner an Access Token should be issued for.

Trusted Client or third party Client?

A trusted Client is created by a developer you know which means it can be trusted with your credentials.

A third party Client is created by a developer you don't know and therefore cannot be trusted with your credentials.

Owner of Access Token?

If it is a system that requires authorization, you should use the Grant Flow Client Credentials Grant.

If you require authorization from an enduser you'll need to make further considerations regarding what Client type to use.

Client Type?

The degree to which the client can protect information is the deciding factor when choosing Grant Flow:

If the client is 'trusted' use Resource Owner Credentials Grant.

If the client is a 'web application' use Authorization Code Grant.

OAuth2 - Endpoints

POST /oauth2/token

This endpoint can be used whenever a Client wants to request an 'access_token' to be issued. The required parameters is determined by what Grant Flow is used.

Example:

• Client Credentials Grant
• Resource Owner Password Credentials Grant
• Authorization Code Grant
• Refresh Token Grant

POST/oauth2/revoke

This endpoint can be used whenever a Client wants to revoke/invalidate a previously issued 'access_token' or 'refresh_token'.

Example:

• Revoking Access Tokens

GET/oauth2/authorize

This endpoint is used when a Client wants to use either "authorization_code" or "implicit" as Grant Flow. This endpoint manages authentication and authorization of the Resource Owner.

Example:

• Authorization Code Grant

GET/oauth2/userinfo

This endpoint allows a Client to fetch the end user's claims. Calls to this endpoint requires that an Access Token is included inside the 'Authorization' header. The response will either contain JSON (Content-Type: application/json) or a JWT (Content-Type: application/jwt).

GET/oauth2/jwks

This endpoint provides keys that are used by Clients and Resource Servers to verify the signature and decrypt 'access_token' that have been issued as JWTs and similarily for OpenId 'id_token'.

GET/oauth2/oidcdiscovery/.well-known/openid-configuration

This endpoint can by used by a Client to fetch metadata describing the Authorization Server.

GET/oidc/logout

This endpoint can be used by a Client to initiate a single logout at the Authorization Server.

GET/oidc/checksession

This endpoint can be used by a Client to monitor the end user's session at the Authorization Server for changes. The main purpose for this is to synchronize the Client's local session with the end user's session at the Authorization Server.

OAuth2 - Access Token

An Access Token can be likened to a wrist band that provides access to carousels in an amusement park. With a wrist band you can ride as much as you want until the amusement park is closes for the day, after which your wrist band expires and you must buy a new one in order to ride carousels the next day. An Access Token follows the same principle where a Client must have an Access Token to invoke protected APIs and request a new one when it has expired. A Client who wants to call an API presents it's Access Token to the API Portal (the man or woman who checks the wrist band in front of the carousel) by an HTTP header.

If the Access Token is valid the API call is routed to the backend. Let us now imagine that the wrist band only gives access to a subset of the carousels that are available in the amusement park where access is determined by the color of the wrist band. One carousel requires a green wrist band while another requires a yellow wrist band. Since you have a green wrist band you will be denied access to the carousel that requires yellow. In the same way a Client can be denied access to an API if the Access Token is not issued for the correct Scope ie. it has the wrong color on it's wrist band.

Which Scopes a Client can issue an Access Token for depends on the roles/groups assigned to the Resource Owner, read more about these terms on the page Terminology. For more info regarding the issuing of an Access Tokens see the page Recommended Grant Flows.

Format

When a Client has their Access Token issued they can come in different formats depending on when you created your application in the API Portal. In this section we clarify what these formats are and what you need keep in mind regarding their issuing.

Opaque

An Access Token that has the format Opaque is a string that does not contain any data and can thus only be validated by the Authorization Server that issued it. The following shows an Authorization Server response to a Client requesting the issuing of an Access Token:

{
    "access_token": "64502333-fa11-4d66-945e-bceee035249c",
    "refresh_token": "9d3ea334-a7a2-387d-a406-57968e6957ff",
    "scope": "device_1",
    "token_type": "Bearer",
    "expires_in": 3600
}
                                

In the response the Client can see which scopes the Access Token was issued for and for how long it can be used.

Considerations when issuing Opaque Access Tokens

When issuing Opaque Access Tokens the API Portal will respond with the same Access Token for each call to /token as long as the "current" token is valid. This allows multiple instances of a Client to share the same Access Token without major problems. However, it is recommended that each instance request a unique Access Token by entering a so-called Device-scope in it's request. Opaque Access Tokens are unique in the API Portal's database based on which Scopes these are issued for. Using Device-scope thus eliminates the risk of different instances of Client interfering with each other. Read more about Device-scope on the page Terminology.

JWT (JSON Web Token)

An Access Token that has the JWT format contains all the data needed to authorize a call from a Client. The JWT that the API Portal issues consists of three parts: header, payload and signature. This is encoded as a Base64URL according to <header>.<payload>.<signature> where each part is decoded into a independent JSON structure. Since a JWT is signed, a Resource Server can self-validate that it is issued by the API Portal by retrieving the public key from the JWKS Endpoint. The advantages of JWT can be summarized in that federation becomes possible as the JWT contains the data needed to authorize API calls and that response times are reduced as validation can be done without network communication with an Authorization Server. Below is an Authorization Server response to a Client requesting the issuing of an Access Token:

{
    "access_token": "eyJ4NXQiOiJaV0kwTW1JNU5ESTJNVFU1T0RZMU0ySmtNREl3WVRFelpXUXdOR1F6TWpSaVptUm1PVEUyTmciLCJraWQiOiJOV1ZtTVRrek1HRTNaV1EzTldKa09UZGtOVFJqWlRJell6VTROell4WWpRek1qazFOelE0WlRnMk1EQmlNV1V4TXpVME1XVTRORFJrWkdFMU5HSmhaQV9SUzI1NiIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJtaXF1ZWxsYSIsImF1dCI6IkFQUExJQ0FUSU9OX1VTRVIiLCJhdWQiOiJoZnljQUt1NmE3aWlsY1hrak15aXRpTXFhY2thIiwibmJmIjoxNjU1OTA5NjA4LCJhenAiOiJoZnljQUt1NmE3aWlsY1hrak15aXRpTXFhY2thIiwic2NvcGUiOiJkZXZpY2VfMSIsImlzcyI6Imh0dHBzOlwvXC9hcGltYW5hZ2VyLWxhYi5sbXYubG0uc2UiLCJleHAiOjE2NTU5MTMyMDgsImlhdCI6MTY1NTkwOTYwOCwianRpIjoiYjAxMDRiM2UtYzc1MS00MTg1LWEwYmQtMWRlNzZiMTIxYTczIn0.QFs5ABKl47QF7G13nC6b-NHdbBDeyzStnV3FuP0A4brR7QmfHgiDlw2_w7iHU_1swYmIYe4QzQEZ9g5e3DJBECExOluXLzOS90mtSZuXqblpjnOCWSwGYAHh2-QlD9d7UyXT9jQMZDdh_kZWB5z89IhVTqn9RrE7rh5gkuOq238bv5uqJN_UQbNrv_n11XrreBPfTgzGaGUC_M0uYGSXNHkxEYpMASURHVngG9PsYYaYHuCZf0iIT3bQEi3Wg4pbaxQkkJc7ytIxy3pcfUcXOiNzikZ-xX9nHvx0FBrQMmVvlWADNMRdbPv88kbR5zHVt2VmMQev5gCko879feB8ug",
    "refresh_token": "9d3ea334-a7a2-387d-a406-57968e6957ff",
    "scope": "device_1",
    "token_type": "Bearer",
    "expires_in": 3600
}
                                

The only difference in the response compared to Opaque is the format of the Access Token. The decoded parts header and payload are shown below:

Header:
{
    "x5t": "ZWI0MmI5NDI2MTU5ODY1M2JkMDIwYTEzZWQwNGQzMjRiZmRmOTE2Ng",
    "kid": "NWVmMTkzMGE3ZWQ3NWJkOTdkNTRjZTIzYzU4NzYxYjQzMjk1NzQ4ZTg2MDBiMWUxMzU0MWU4NDRkZGE1NGJhZA_RS256",
    "alg": "RS256"
}
Payload:
{
    "sub": "miquella",
    "aut": "APPLICATION_USER",
    "aud": "hfycAKu6a7iilcXkjMyitiMqacka",
    "nbf": 1655909608,
    "azp": "hfycAKu6a7iilcXkjMyitiMqacka",
    "scope": "device_1",
    "iss": "https://apimanager-lab.lmv.lm.se",
    "exp": 1655913208,
    "iat": 1655909608,
    "jti": "b0104b3e-c751-4185-a0bd-1de76b121a73"
}
                                

Considerations when issuing JWT Access Tokens

When issuing an Access Token with the JWT format, the API Portal will revoke the previous Access Token for each call to /token. This creates problems if multiple instances of Client share the same Access Token. To prevent this, each instance must request a unique Access Token by entering a so-called Device-scope in its request. Using Device-scope eliminates the problem that different instances of Client interfere with each other. Read more about Device-scope on the page Terminology.

Generate Access Token with Scopes

For Access Tokens where the Grant Flow is initiated by a machine see Recommended Grant Flows for more info. To generate an Access Token with Scopes via the API Portal, follow the steps below:

1. Navigate to the list of Applications and click on the Application that should generate an Access Token.

   

2. Click on "Application Keys" and then on "Generate Access Token".

   

3. Click on the "drop-down" list and select which Scopes the Access Token is to be issued for, then click on "Generate". Only Scopes associated with the APIs that your Application subscribes to are selectable.

   

4. Copy the Access Token by clicking the icon and then on "Close".

   

How do I know which Scopes my Access Token needs?

The Scopes required by an API are usually described in the accompanying documentation, another way to see which Scopes are required is to navigate to the Try Out console:

1. Navigate to the start page and select an API to consume.

   

2. Click on the "Try Out" tab and review the API's resources to see which Scopes are required.

   

OAuth2 - Client Credentials Grant

Recommended Use

This Grant Flow is best suited for machine-to-machine communication when authentication of an end user isn't needed.

Flow

Preconditions: The developer provides Consumer Key and Consumer Secret (created in the API Portal) to the Client.

1. The Client requests an Access Token by authenticating using the Consumer Key and Consumer Secret at the Authorization server.
2. The Authorization Server responds with an Access Token.
3. The Client calls an API by including the Access Token in a HTTP Header.

Request

The Client sends a POST-request with the following parameters to the Authorization Server:

• grant_type with the value 'client_credentials'.
• client_id with the value of Consumer Key.
• client_secret with the value of Consumer Secret.
• scope (optional) a whitespace delimited list of scopes.

Exemple request (cURL) using Client Credentials Grant to issue an Access Token:

curl -v -X POST -H "Authorization: Basic <base64 encoded consumerKey:consumerSecret value>" -d "grant_type=client_credentials" -H "Content-Type:application/x-www-form-urlencoded" https://apimanager.lantmateriet.se/oauth2/token
                                

Response

Example of a response with a issued Access Token:

{ 
    "access_token":"b5ea876f-8df7-3102-a7db-a30205a986ba",
    "scope":"am_application_scope default",
    "token_type":"Bearer",
    "expires_in":3600
}
                                    

OAuth2 - Resource Owner Credentials Grant

Recommended Use

This is suitable when you want to issue and access token for an end user and provide it to the Client. The basis of the Grant Flow is that the end user has sufficient trust for the Client to such a degree that their credentials can be shared with it.

Flow

Preconditions: The devloper provides the Consumer Key and Consumer Secret to the Client (the developer has created these in the API Portal).

1. The Client requests username and password from the end user.
2. The Client requests that the Authorization Server issues an Access Token using the end users username and password along with the Client's own Consumer Key och Consumer Secret.
3. The Authorization server responds with an Access Token and Refresh Token.
4. The Client calls the API with the Access Token in a HTTP Header.

Request

The Client sends a POST-request with the following parameters to the Authorization Server:

• grant_type with the value 'password'.
• client_id with the value of Consumer Key.
• client_secret with the value of Consumer Secret.
• username with the end user's username.
• password with the end user's password.
• scope (optional) a whitespace delimited list of scopes.

Exemple request (cURL) using Resource Owner Password Credentials Grant to issue an Access Token:

curl -v -X POST -H "Authorization: Basic <base64 encoded consumerKey:consumerSecret value>" -d "grant_type=password&username=<username>&password=<password>&scope=scope1 scope2 ... scope_n" -H "Content-Type:application/x-www-form-urlencoded" https://apimanager.lantmateriet.se/oauth2/token
                                

Response

Example response with two issued tokens, one Access Token and one Refresh token:

{ 
    "access_token":"b7e055ca-1431-3f64-8856-3d6412493162",
    "refresh_token":"dd2a08e0-d132-3e28-948c-273a6a2050a8",
    "scope":"default",
    "token_type":"Bearer",
    "expires_in":3600
}
                                    

OAuth2 - Authorization Code Grant

Recommended Use

This flow should be used when you want to issue an Access Token for a end user and the Authorization Code Exchange is handled serverside by the application. Due to security considerations the Access Token, Refresh Token, Consumer Key, Consumer Secret shouldn't be exposed to a browser.

Flow

Preconditions: The developer provides the Consumer Key and Consumer Secret belonging to the Client, these keys and a callback URL have been created by the developer in the API Portal.

1. The Resource Owner requests a protected resource or explicitly chooses to sign in.
2. The Client redirects the Resource Owner to a sign in form that is hosted on the Authorization Server.
3. The Resource Owner signs in.
4. The Authorization Server redirects the browser back to the provided callback URL together with an Authorization Code.
5. The Client requests the Authorization Code to be exchanged for an Access Token while also providing the Consumer Key and Consumer Secret.
6. The Authorization Server responds with an Access Token and a Refresh Token (and in some cases IdToken).
7. The Client makes a call to the API making sure to include the Access Token in a HTTP Header.

Request - Sign In

The Application redirects the end user to the sign in form on the Authorization Server with the below parameters:

• response_type with the value 'code', which signifies that you want the Authorization Server to respond with an Authorization Code.
• client_id Provide the Consumer Key belonging to your application.
• redirect_uri The callback url that has been configured for the application, the end user will be redirected to it after signing in.

• state (optional)

  the state parameter have to use cases. The Client has an opportunity to store data mapped to the value of the state parameter which can be accessed when the Resource Owner is redirected back to the callback URL post sign in.

  the state parameter also functions as a CSRF mitigation if it contains an unguessable value for each request and when the end user gets redirected from the sign in it can be verified against the original value.

• scope (optional) a whitespace delimited list of scopes.

  info

  If you want to enable Open Id Connect you provide scope=openid.

Example of the Authorization Request (URL):

https://apimanager-ver.lantmateriet.se/authorize?response_type=code&client_id=ldevT_hY8SsDWY83kJi8m8tVpYEa&redirect_uri=https://www.minApplikation.se/&state=Y83kJi
                                

Example of the redirect back to the callback URL:

https://www.minApplikation.se/?code=81df7476-4367-3f30-a41b-3ebae6426b55&state=Y83kJi
                                

Request - Code Exchange

The Client exchanges the recieved 'code' for an Access Token by sending a POST-request with the following parameters to the Authorization Server:

• grant_type with the value 'authorization_code'.
• code with the value of the 'code' parameter.
• redirect_uri with the value of the registered callback URL.

Example Token Request (Code Exchange) using curl:

curl -v -X POST -H "Authorization: Basic <base64 encoded consumerKey:consumerSecret value>" -d "grant_type=authorization_code&code=81df7476-4367-3f30-a41b-3ebae6426b55&redirect_uri=https://www.minApplikation.se/" -H "Content-Type:application/x-www-form-urlencoded" https://apimanager.lantmateriet.se/oauth2/token
                                

Response

Example response with two issued tokens, one Access Token and one Refresh token:

{ 
    "access_token":"b7e055ca-1431-3f64-8856-3d6412493162",
    "refresh_token":"dd2a08e0-d132-3e28-948c-273a6a2050a8",
    "scope":"default",
    "token_type":"Bearer",
    "expires_in":3600
}
                                    

OAuth2 - Refresh Token Grant

Recommended Use

After an Access Token has expired you can use a Refresh Token to renew it.

Flow

Preconditions: Access Token has been issued with one of the following Grant Flows: Resource Owner Password Credentials Grant or Authorization Code Grant.

1. The Client requests a new Access Token using a Refresh Token.
2. The Authorization Server responds with an Access Token and a new Refresh Token.
3. The Client calls an API with the Access Token in the 'Authorization' HTTP Header.

Request

Example of a cURL call with Refresh Token to issue a new Access Token:

curl -d "grant_type=refresh_token&refresh_token=<refresh_token>" -H "Authorization: Basic <Base64Encoded(Client_Id:Client_Secret)>" -H "Content-Type: application/x-www-form-urlencoded" https://apimanager.lantmateriet.se/oauth2/token
                                

Response

{ 
    "access_token":"2c7b4bc0-fcd1-3a5e-9cb0-5b65ded21eb7",
    "refresh_token":"15f473a9-ebfb-34ff-9b1e-a7e9bd6bd5ad",
    "scope":"default",
    "token_type":"Bearer",
    "expires_in":3600
}
                                    

OAuth2 - Revoking Access Tokens

You can revoke an Access Token or Refresh Token.

Request

Example of a cURL call to revoke an Access Token:

curl -v -d "token=<access_token>" -H "Authorization: Basic <Base64Encoded(Client_Id:Client_Secret)>" -H "Content-Type: application/x-www-form-urlencoded" https://apimanager.lantmateriet.se/oauth2/revoke
                                

Response

The response will have the HTTP Status 200 with the following headers:

Revokedaccesstoken: a0d210c7a3de7d548e03f1986e9a5c39
Authorizeduser: admin@carbon.super
Revokedrefreshtoken: 5e87a8235cd4d066e15c4c989f5ecf94
Content-Type: text/html
Pragma: no-cache
Cache-Control: no-store
Date: Tue, 23 Aug 2016 19:28:52 GMT
Transfer-Encoding: chunked
                                    

Content-Type: text/html
Pragma: no-cache
Cache-Control: no-store
Date: Tue, 23 Aug 2016 19:31:45 GMT
Transfer-Encoding: chunked