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.

Note

This page uses https://provetcloud.com/54321/ as URL for request examples. When building your API access, replace the domain with the same domain you can see when using the application. For example: us.provetcloud.com, enterprise.provetcloud.com.

Note

This page uses client_id and client_secret values as HTTP body parameters for simplicity. These can also be passed as HTTP Basic Authentication in Authorization header. The header is also the preferred way.

Request and response types

Note that OAuth2 token, refresh_token, revoke_token endpoints accept data (Content-Type header) as

  • application/x-www-form-urlencoded

  • multipart/form-data

and return data as application/json responses.

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

Note

This is usually handled automatically by an OAuth 2.0 client, and is not normally required to implement yourself. The process is done here manually for documentation purposes.

First, an authorization code must be generated. This includes logging in to Provet Cloud with working credentials.

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 headers:

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

Request POST payload:

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

Response headers:

Content-Type: application/json

Response payload:

{
    "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 when accessing the API:

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 headers:

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

Request POST payload:

grant_type=refresh_token
&refresh_token=EaJvK6gfP2AxxnPOKVCe1B4V4hWKwo

Response headers:

Content-Type: application/json

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 headers:

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

Request POST body:

grant_type=client_credentials
&client_id=d3FXJ6jGrnZkcVEEsDKUclf3xgiYIAxpb0jIjuPa
&client_secret=fqB7OWVQZ0nwONDRvYVk8vSPGywZbPb9EwLyI5TDlmqn

Response headers:

Content-Type: application/json

Response payload:

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

The access_token can then be used in a HTTP header when accessing the API:

Authorization: Bearer W660DEnZp75flqqkpetbErALcQDXCC

Example: Revoke an access token

Request URL:

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

Request headers:

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

Request payload:

token_type_hint=access_token
&token=B8eFskUa5dYOmb1l9vx9tMSOzT1FAV
&client_id=d3FXJ6jGrnZkcVEEsDKUclf3xgiYIAxpb0jIjuPa
&client_secret=fqB7OWVQZ0nwONDRvYVk8vSPGywZbPb9EwLyI5TDlmqn

Example: Revoke a refresh token

Refresh tokens can be revoked with a similar call.

Request URL:

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

Request headers:

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

Request payload:

token_type_hint=refresh_token
&token=KIbP0QEmKzG6ZGgPk4gCdmZ15ih9mR
&client_id=d3FXJ6jGrnZkcVEEsDKUclf3xgiYIAxpb0jIjuPa
&client_secret=fqB7OWVQZ0nwONDRvYVk8vSPGywZbPb9EwLyI5TDlmqn