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