API Security

The security used in our APIs are protected using both the OAuth 2.0 Client Credential Flow and a Subscription Key. This WIKI page assumes that you have already been issued the security details required to access the intended API.

Authentication Flow

The following diagram is a high level representation of the authentication flow that will be used when accessing APIs.

Picture

Step 1 - Requesting an Access Token

An access token is supplied by sending an application/x-www-form-urlencoded POST request our identity providers token end point.

Token Endpoint URL
The POST request should be issued to the following token URL. Please note that the tenancyid will be supplied to you.
https://login.microsoftonline.com/<tenancyid>/oauth2/v2.0/token/

 Body Parameters
The body of the request will include the following parameters:

Example Request

POST /abc1234567-03ab-6b70-8a27-abc12345/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=12345&client_secret=xxxxxxxx&grant_type=client_credentials&scope=api://e5g957k-75c6-4be7-af7b-f0b70440d0a2/.default

Example Response

{
 "token_type": "Bearer",
 "expires_in": 3599,
 "ext_expires_in": 3599,
 "access_token": "......eyJ0eXAiOiJKV1QiLCJhbG...."
}

Step 2 - Access token returned to API client 

If all client credentials are valid, the endpoint will issue a token for accessing the intended API. The access token be in form of a JWT (JSON Web Token) and will be signed using the RS256 algorithm. The token will expire in 60 minutes from the point of being issued. After your token expires you will retrieve a 401 (Unauthorized) response from the API you are trying to access. If this occurs, you will need to request a new token.

Please note that you should not request a access token before every API request as this significantly degrade performance. Holding the access token in memory and reusing the same token until it expires will aid better performance.

Tip:  A good website for viewing the encoded JWT access tokens is https://jwt.ms/ 

Step 3 – API Request

Now you have acquired the access token, the next step is to call the API resource. You call the API resource method by passing the access token and subscription key in the request headers. 

Example Request

POST /demo-api/v1/saymessage HTTP/1.1
Host: api.ardengemcsu.nhs.uk
Authorization: bearer <access token>
Ocp-Apim-Subscription-Key: <subscription key>
Content-Type: application/json
 
{"message" : "This is my message"}

Step 4 - API Response

If the access token and subscription key are validated successfully, the intended method will be called and the appropriate response returned.

Example Response (Successful)

{ "message": "This is my message" } 

If for any reason the subscription key or JWT access token will lead to a 401 unauthorized response. 

Example Response (Unauthorized)

{ "statusCode": 401, "message": "Unauthorized. Access token is missing or invalid."}