Skip to main content

Authentication

The PAL API is secured with the OpenID Connect (OIDC) and OAuth protocols. In order to receive data from the HTTP Endpoint, each call will need to be passed a Bearer Token in the Authorization Header. You can get a Bearer Token through making an HTTP POST to our OCAS Identity Server (OIDS) token endpoint.

Bearer Token Expiry​

The Bearer Token, once issued, will last only for 1 hour. You will need to get a new Bearer Token to make any protected API call requests after the Token expiry has elapsed. If a request is made with an expired or otherwise invalid Bearer Token, the PAL API will respond with an HTTP 401 error response code.

How to Get a Bearer Token​

To get the Bearer Token, you need to perform an HTTP POST action to the token endpoint /auth/connect/token and include identifying credentials as follows:

  1. OCAS will provide you with <clientId>, <clientSecret>, <username>, and <password>, which should be replaced in the form-urlencoded params.

    Example Request:

POST /auth/connect/token HTTP/1.1
Host: authenticate.uat.ocas.ca
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

client_id=<clientId>&client_secret=<clientSecret>&username=<username>&password=<password>&grant_type=password&scope=isals_api.public

Example Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "isals_api.public"
}

  1. In the above response, 'access_token' is the actual token needed to make further API calls. When the token is generated, that access_token is valid for 1 hour (3600 seconds), which should be more than enough for any scheduled task or cronjob, consuming data. You will want to copy/store the value for access_token in a variable, then construct another HTTP Request with the word Bearer <token_value> in the Authorization Header as follows:

    GET /api/v1/diagnostics/authorization HTTP/1.1
    Host: <PAL>.ca
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
    Accept: application/json
    Cache-Control: no-cache

    Example Response:

    {
      "name": "Partner User",
      "customerCode": "TEST",
      "roles": "PALSis"
    }

You now have a token that you can use for all subsequent PAL API endpoint calls within the Token expiry lifetime.

Bearer Token Expiry​

The Bearer Token, once issued, will last only for 1 hour. You will need to get a new Bearer Token to make any protected API call requests after the Token expiry has elapsed. If a request is made with an expired or otherwise invalid Bearer Token, the API will respond with an HTTP 401 error response code.

Subscription Key​

In addition to an Authorization token, requests to the API will also need to include a Subscription Key. This Subscription Key will be assigned to you when you request access and allows for requests to be handled through our API Management Gateway.

The Subscription Key must be included as an HTTP header named Subscription-Key.

Example Request:

GET /international/pals/sis/pal-events/pending HTTP/1.1
Host: apis.uat.ocas.ca
Subscription-Key: <key>
Authorization: Bearer <token>