OAuth 2.0

Provet Cloud supports the industry-standard OAuth 2.0 authorization mechanism. It allows third-party systems and integrations to access Provet Cloud REST API securely without storing usernames or passwords.

Supported grant types

Authorization code
Client credentials

Authorization code should be used in cases where users access the API as themselves, like user interfaces.

Client credentials should be used in cases where the API is accessed by background systems only.

PKCE is supported for Authorization code flow, and required for public client types.

Permissions

All API access uses Provet Cloud’s permission system. Integrations using Authorization code flow will use the logged in user’s permission for API access. Integrations using Client credentials flow are bound to a Provet Cloud virtual user. This virtual user must have the appropriate permissions for whatever actions the integration wants to perform.

Available scopes

Provet Cloud supports these scopes:

restapi - Access the REST API. This is the default if no scopes are requested.
openid - Optional. Access to additional details about the user. Useful only for Authorization code flow.

Token expiry

Access token’s time-to-live: 10 hours
Refresh token’s time-to-live: 30 days after latest access token

Access tokens expire 10 hours after they are generated. After that, you have to use the refresh token and the token endpoint to generate a new access token. Refreshing the access token may also return a new refresh token. OAuth 2.0 refresh tokens will expire if the token is not used to generate new access tokens in 30 days.

If your refresh token expires, you are asked to login again to Provet Cloud to generate tokens.

Client credentials flow uses only access tokens.

Connecting

Connecting integration must be configured into Provet Cloud by Provet Cloud’s support team. Client ID and client secret values will be provided to the integration developer once the configuration is completed.

Each Provet Cloud instance has its own OAuth 2.0 endpoints.

Authorize: https://provetcloud.com/<provet id>/oauth2/authorize/
Token: https://provetcloud.com/<provet id>/oauth2/token/
Revoke: https://provetcloud.com/<provet id>/oauth2/revoke_token/
User info (if using OpenID): https://provetcloud.com/<provet id>/oauth2/userinfo/

Authorization code example: Get tokens

First, an authorization code must be generated. This is usually handled by an OAuth 2.0 client.

Request URL:

https://provetcloud.com/54321/oauth2/authorize/
?response_type=code
&client_id=4384b8978abd4502b9c3c9d4a1b73a37
&scope=restapi%20openid
&redirect_uri=https%3A%2F%2Fyourapp.example.com%2F

After a successful login and authorization, you are redirected to the URL specified in redirect_uri with a code parameter (in this example, https://yourapp.example.com/?code=987654321). The authorization code in the parameter can then be used to generate the initial tokens.

Request URL:

https://provetcloud.com/54321/oauth2/token/

Request POST payload:

grant_type=authorization_code
&code=987654321
&redirect_uri=https%3A%2F%2Fyourapp.example.com%2F
&client_id=4384b8978abd4502b9c3c9d4a1b73a37

Response:

{
    "access_token": "G21AMJFo2J83JuAzurk1hMbCq9Hik7",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "restapi openid",
    "refresh_token": "EaJvK6gfP2AxxnPOKVCe1B4V4hWKwo"
}

The refresh_token should be stored safely for future use. The access_token can then be used in a HTTP header:

Authorization: Bearer G21AMJFo2J83JuAzurk1hMbCq9Hik7

Authorization code example: Get a new token

If your access token has expired, you can request a new access token using your refresh token.

Request URL:

https://provetcloud.com/54321/oauth2/token/

Request POST payload:

grant_type=refresh_token
&refresh_token=EaJvK6gfP2AxxnPOKVCe1B4V4hWKwo

Response payload:

{
    "access_token": "B8eFskUa5dYOmb1l9vx9tMSOzT1FAV",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "restapi",
    "refresh_token": "KIbP0QEmKzG6ZGgPk4gCdmZ15ih9mR"
}

Client credentials example: Get access token

Request URL:

https://provetcloud.com/54321/oauth2/token/

Request POST body:

grant_type=client_credentials
&client_id=d3FXJ6jGrnZkcVEEsDKUclf3xgiYIAxpb0jIjuPa
&client_secret=fqB7OWVQZ0nwONDRvYVk8vSPGywZbPb9EwLyI5TDlmqn

Response payload:

{
  "access_token": "W660DEnZp75flqqkpetbErALcQDXCC",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "restapi"
}

Example: Revoke an access token

Request URL:

https://provetcloud.com/54321/oauth2/revoke_token/

Request payload:

token_type_hint=access_token
&token=B8eFskUa5dYOmb1l9vx9tMSOzT1FAV

Refresh tokens can be revoked with a similar call.

Request payload:

token_type_hint=refresh_token
&token=KIbP0QEmKzG6ZGgPk4gCdmZ15ih9mR