14.10.3 Using REST API with an OAuth Client

Use an OAuth client to get a bearer token and call authorized REST APIs.

To use an OAuth client, the third party system starts by acquiring a bearer token using the client id and client secret provisioned for their integration. You can test the scenario on the command line using curl. Notice that the URL shares the same base as your REST APIs up to an including the schema alias (e.g. cloudcompanion). Then it ends with the /oauth/token path segments. The ‑‑data flag makes curl send a POST request with Content‑Type header set to application/x‑www‑form‑urlencoded and a request body containing grant_type=client_credentials. If the client id and secret are valid, the token endpoint returns a JSON response containing the bearer-type access token. It also includes the number of seconds that the token is valid. In the example below, the token expires in 3600 seconds, or 1 hour.

$ curl --user "QvUVx6Gp8P02dTb0C-II1A..:szUul--kEJ1Te-kS454_tQ.." \
--data "grant_type=client_credentials" \
https://example.com/ords/cloudcompanion/oauth/token

{"access_token":"SNVDe2Tjough44I_X6tmXg","token_type":"bearer","expires_in":3600}

Once the system gets its token, for an hour it can send that token in the Authorization header of any REST API request it makes to the APIs their OAuth client's role authorizes them to use. For example, using curl this access looks like this. Notice the word Bearer, followed by a space, precedes the token value in the header.

$ curl -H "Authorization: Bearer SNVDe2Tjough44I_X6tmXg"  \
https://example.com/ords/cloudcompanion/v1/actionitems/14

As long as the token is still valid, your REST API returns the expected response. After an hour, the external system can contact the token URL again to get a "fresh" token. If they fail to get a new token before it expires, their attempt to use an expired token will response with an HTTP 401 Unauthorized error, including the payload below:

{
    "code": "Unauthorized",
    "message": "Unauthorized",
    "type": "tag:oracle.com,2020:error/Unauthorized",
    "instance": "tag:oracle.com,2020:ecid/636fea296204b162106f0cdb5d7e22bc"
}