Authorization

Successful invocation of this API will result in the user being redirected to the URL specified in the API key (redirect_uri below). Use the API key created in the API Key section above as applicable for each required parameter.

GET
/oauth/authorization

Request Parameters

Name Type Description Required
apiKey string Key Value as configured in Rev Yes
signature string This is a base 64 encoded string computed from the hash generated by signing verifier (below) using HMAC SHA 256 algorithm. It uses the apiKey secret as the key for signing. This is to make sure that the API sending the request has the right secret key and it has not been compromised. This value must be URL encoded. Yes
response_type string Set to code. This value is case-sensitive. Yes
redirect_uri string URL of Web page to load after Rev credentials have been entered by the user. This page is where the final authentication steps will be performed and from which all subsequent API calls may be made. This value must be URL encoded. Yes
verifier string This is a combination of Apikey and current timestamp in UTC (in the format “Apikey::Timestamp”) that is used for verifying the authorization request.The date/time stamp used typically will be the current date/time at the time of the request. It must meet the following criteria. UTC format, less than 30 minutes from the current time, in a valid date and time format. This value must be URL encoded.
state string This field is optional. It can be used to pass state information from the invoking application. The state information will be passed to the redirect_uri page when it is loaded.

Example Request

{
    "apiKey" : "abc123",
    "signature" : "string",
    "response_type" : "code",
    "redirect_uri" : "https://website.company.com/page",
    "verifier" : "abc123::2017-08-31T15:00:10.495Z",
    "state": "state"
}

Response Codes

Code Description
200 ok. Successful response. After validating the ApiKey and signature, user is redirected back to login page with a reference to the redirect URI. [Redirect URI]?auth_code=&state=state or [Redirect URI]?error=access_denied
401 Unauthorized error
500 Internal server error

Access Token Request

This is used to obtain the access token to identify the Rev user that has successfully been granted access to Rev. Used for initial requests and to extend session.

POST
/oauth/token

Request Parameters

Name Type Description Required
authCode string Value of XXX for initial request and extend session.  Yes
apiKey string Key Value as configured in Rev above  Yes
grantType string This field is required. The value should be set to “authorization_code” for the initial session request and set to “refresh_token” to extend an existing session.  Yes
redirectUri string As specified in the API key definition. Required.  Yes
refreshToken string Not applicable for initial request and can be omitted. After the initial request, however, this value must be present and the value returned from the initial call for session extension. Note that this value may remain the same for a given session and can be used repeatedly in extend session requests as long as the session remains valid. Each extend session will generate a new accessToken value therefore the full authorization string must be recalculated after each extend session request before using in subsequent API calls.  Not required for initial request.  Required for session extension.

Example Request

{
"authCode" : "nxkJnMQVKdGiQm18vdzq5yXTZLSw5bFHvXHcUl9x6DuhbEiQ2fC6U872CNS3M6ORyz-K6JFMFI8U0rzxxC5xo_c6dMyLd1h9OLZsRbtK8Sc1",
"apiKey" : "1234qwer",
"grantType" : "authorization_code",
"redirectUri" : "https://url.company.com/webpage",
"refreshToken" : "8OuGKKxt5KBBq0bRgrtYZhTwDyX8bhqmpOhrrZTt3ygDyX8bhqmpOhrrZTt3ygDyX8bhqmpOhrrZTt3yg"
}

Example Response

{
"accessToken" : "nxkJnMQVKdGiQm18vdzq5yXTZLSw5bFHvXHcUl9x6DuhbEiQ2fC6U872CNS3M6ORyz-K6JFMFI8U0rzxxC5xo_c6dMyLd1h9OLZsRbtK8Sc1",
"refreshToken" : "LSw5bFHvXHcUl9x6DuhbEiQ2fC6U872CNS3M6ORyz-K6JFMFI8U0rzxxC5xo_c6dMyLd1h9OLZsRb",
"userId" : "b9a38810-cd84-480c-8232-5ec6320a6b47",
"expiration" : "2017-08-31T15:00:10.495Z",
"issuedBy": "VBrick"
}

Definitions

Return Description
issuedBy issuer of the token (always “VBrick” for Rev)
accessToken unique string granted by the issuer
refreshToken for use in extended this session API
expiration UTC date/time at which the session will expire. The length of time until expiration will be determined by the “Session Inactivity Timeout (in minutes)” specified in the administrative settings of Rev under System Settings->Security.
userID Unique GUID of the Rev user who has been authorized

Response Codes

Code Description
200 ok
401 Unauthorized error
500 Internal server error