Step 4: Get/Refresh a Token

Once an authorization code is available, obtain an OAuth2.0 id_token. The id_token provides a session (with scope and expiration) that client applications use to make API calls. The same API can also be used to get a refresh token in case of token expiry. The process includes the following:

Request

Your application passes the following to obtain a token:

URL: {{HOST}}/oidc-provider/v1/oauth2/token

Operation Type: POST

Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type - Should be set to "authorization_code" for new token/ "refresh_token" in case the user wants to renew an expiring token

client_id - Client id of the API account

code_verifier - Plain text version (43-128 character long string) of the "code_challenge" parameter in the "signin" API (required for grant_type=authorization_code)

code - Should be set to the "auth_code" from "signin" or "refresh_token" from a previously obtained token

Sample Request:

{

grant_type:"authorization_code",

client_id:"MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwLjkyMWU2YzBiLTY2MzYtNDkzMi04NGU4LTZlZmRhMDEzYTE5Ng==",

scope:"openid",

code:"LTAwMDwLmJQZVhwT3BFT1FrZnlyZ0JWcEFjcWFRQ2ZBVUhYeVlFaXhLYlFrRFRWaU5XaFI=",

code_verifier: "-._~QWERTYUIOPASDFGHJKLZXCVBNMqwertyuiopasdfghjklzxcvbnm-._~"

}

Response

The response returns the OAuth2.0 token string if the request is successful. The following are samples of the responses you can expect.

HTTP Status 200: A successful response returns your id_token and refresh token

{

"id_token": "<token string>",

"token_type": "Bearer",

"expires_in": 86400,

"refresh_token": "<token string>"

}

HTTP Status 401: Authentication Error

{

"status": 401,

"message": "AUTHENTICATION_CODE_NOT_FOUND",

"code": "RECORD_NOT_FOUND"

}

JSON Response:

Contains the Access Token request output in JSON format. The response contains the attributes id_token, refresh_token, token_type, and expires_in.

The id_token identifies your client access in Oracle and is used for subsequent REST API calls. This token is encoded following the JSON Web Token (JWT) standard and is valid for 14 days.

The token_type identifies the Access Token as a "Bearer" token type. In future requests, you can use this token type to identify your token in the Authorization header of your request.

To use this token in your request, set the "Authorization" key in the request header to "Bearer <id_token>"

The expires_in identifies the validity period of the Access Token.

The refresh_token identifies the client access in Oracle and can be used to get a new id_token (using grant_type=refresh_token in the "token" API call) when the current one expires. The refresh_token is valid for 15 days.

The id_token is used as the Bearer Token in the authorization header of all API calls. Clients are responsible for refreshing the token before validity period expiration. This needs to be done a day or two before the refresh token expires (13 days after the token has been issued).

If after a Reporting and Analytics upgrade an "AUTHENTICATION_INVALID" error is noticed, clients need to go through the authentication process again and obtain a new token. It is suggested that a client implemented for 9.1 automate a reauthentication call using the existing refresh token, as the signing key rotates on upgrade.