Authentication Methods

Change log:

The purpose of this section is to describe how to authenticate when making API calls using the Rator REST API.

OAuth 2

For obtaining access/bearer tokens the following of RFC-6749's only "password" grant flow is supported, plus a custom password flow for authentication of Operators:

With Java 21 upgrade (REST v17.0, core 11.23), an additional grant flow is supported: client_credentials

1. Resource Owner Password Credentials Grant 

Useful if you have the end user's password but you want to use a more secure end user access token instead. 

^{$ curl -v -X POST -u myclientid:myclientsecret http://host:port/appcontext/oauth/token -H "Accept: application/json" -d "grant_type=password&username={myusername}&password={mypassword}&brandKey={myBrandKey}"}

2. Operator Password Credentials Grant 

Useful if you have the end user's password but you want to use a more secure end user access token instead. 

^{$ curl -v -X POST -u myclientid:myclientsecret http://host:port/appcontext/oauth/token -H "Accept: application/json" -d "grant_type=operator_password&username={myoperatorusername}&password={myoperatorpassword}&brandKey={myBrandKey}"}

3. Client Credentials Grant 

Useful for M2M scenarios

^{$ curl -v -X POST -u myclientid:myclientsecret http://host:port/appcontext/oauth/token -H "Accept: application/json" -d "grant_type=client_credentials&operator=(myoperatorusername)&brandKey={myBrandKey}"}

Making Requests

Once you have an access token, one can use it in a request as a request header: Authorization: Bearer {access_token}

Refresh Tokens

The access tokens expire after an interval that is configured in OAUTH_CLIENT_DETAILS table. When this happens you will get 401 responses.

^{$ curl -X POST -u myclientid:myclientsecret http://host:port/appcontext/oauth/token -H "Accept: application/json" -d "grant_type=refresh_token&refresh_token={refresh_token}&brandKey={myBrandKey}"}

Scopes

Scopes are not used by Rator REST API.