Lookups | Geo data | Files
Authentication
Our authorization process it is based on oAuth2 with a little twist.
All integrators will receive from Gryphtech an Api Key, a Secret Key and an Integrator ID. They will have to use these elements to receive the authorization token and in every call they make to the API.
Every authorization token has an expiry date. Integrators can check the validity of token before they make the call to the API or they can request a new token.
Supported Methods
Read also how to use authentication in your API calls
All authentication methods calls have to be made with HTTP POST.
Getting the authorization token
All API requests must contain the Api Key and Authorization Token. As Api Key is a known constant, obtaining the authorization token is the key of using the API.
Call
POST oauth/token
Api Key and Secret Key must be sent in the body of the request:
grant_type=authorization_code&client_id={Api Key}&code={Secret Key}
Where {Api Key} and {Secret Key} are values preasigned by Gryphtech for each integrator.
Body MUST be URL encoded. The encoded body will look something like this:
=grant_type%3Dauthorization_code%26client_id%3D10D35802-C92A-42B3-88FC-A4489A3CD619%26code%3D666E465A-6012-45B9-AA1E-ADDD728F61DE
IMPORTANT:
Please note "=" character at the begining of body content. It
must be there.
Request
The entire call should look something like this (some headers where excluded for brevity):
POST https://rexapi.local.gryphtech.com/api/v1/oauth/token HTTP/1.1 Accept: application/xml; charset=utf-8 Content-Type: application/x-www-form-urlencoded =grant_type%3Dauthorization_code%26client_id%3D10D35802-C92A-42B3-88FC-A4489A3CD619%26code%3D666E465A-6012-45B9-AA1E-ADDD728F61DE
Depending on the type of response content expected, Accept header must be set to application/json; charset=utf-8 or application/xml; charset=utf-8
Response XML
HTTP/1.1 200 OK Content-Type: application/xml; charset=utf-8 Date: Tue, 02 Dec 2014 03:30:56 GMT <AccessTokenResponse> <access_token>pfl4PLrrHKChIRoDS2O9Wfoyr1yjKgbEjCxk+adBohqos93Ev0cbS=</access_token> <token_type>token</token_type> <expires_in>172800</expires_in> </AccessTokenResponse>
Response JSON
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 02 Dec 2014 03:30:56 GMT
{
"access_token":"pfl4PLrrHKChIRoDS2O9Wfoyr1yjKgbEjCxk+adBohqos93Ev0cbS="
"token_type": "token",
"expires_in": 172800,
"refresh_token": null
}
- access_token
- This is the authorization token. It must be used in all API calls.
- expires_in
- This represent the life span of the authorization token. Its value is in seconds. In our example, 172800 seconds = 48 hours. This means that this token will expire (no longer be valid) after 48 hours from the moment it was generated.
- token_type
- It will always return "token"
- refresh_token
- It will always be NULL. We do not support refresh token.
Verify if the token is still valid
Optional, you can verify if the token is still valid.
Call
POST oauth/ValidateToken?apiKey={ApiKey}&token={Authorization Token}&integratorID={Integrator ID}
Required parameters:
- Api Key
- the application key preassigned to you by Gryphtech
- Authorization Token
- the authorization token obtained previously
- Integrator ID
- the inntegrator ID preassigned to you by Gryphtech
Request
POST https://rexapi.local.gryphtech.com/api/v1/oauth/ValidateToken?apiKey=10D35802-C92A-42B3-88FC-A4489A3CD619&token=pfl4PLrrHKChIRoDS2O9Wfoyr1yjKgbEjCxk%2BadBohqos93Ev0cbSBCpturiX556GIt9990allcXeGTWnTeo6XxPEb02%2F3K9sD6XQgmY%2B2dl5%2Bn4B%2BJb7QwUtq%2FMvdlKZtBvWopRUFE%3D&integratorID=1005001 HTTP/1.1 Accept: application/json; charset=utf-8
Response XML
HTTP/1.1 200 OK Content-Type: application/xml; charset=utf-8 <TokenValidationResponse> <tokenstatus>Valid</tokenstatus> <expires_in>2014-12-03T22:30:56</expires_in> </TokenValidationResponse>
Response JSON
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"tokenstatus": "Valid",
"expires_in": "2014-12-03T22:30:56"
}
- tokenstatus
- Valid: If everything is OK.
NoAccess: Invalid Integrator ID
Expired: The life of the token expired.
Invalid: Invalid Api Key, Token, Integrator ID combination - expires_in
- The date and time when token will expire. The time is oAuth server time: Eastern Time (US & Canada)
Verify client
Optional, you can verify if Api Key, Secret Key and Integrator ID are registered and valid with the oAuth server. Also you can find out what will be the expiration period for all your future authorization tokens.
Call
POST oauth/ValidateClient?integratorID={IntegratorID}
Required parameters:
- {IntegratorID}
- the inntegrator ID preassigned to you by Gryphtech
Api Key and Secret Key must be sent in the body of the request:
client_id={Api Key}&secret={Secret Key}
Where {Api Key}, {Secret Key} and {Integrator ID} are values preassigned by Gryphtech for each integrator.
Body MUST be URL encoded. The encoded body will look something like this:
=client_id%3D10D35802-C92A-42B3-88FC-A4489A3CD619%26secret%3D666E465A-6012-45B9-AA1E-ADDD728F61DE
IMPORTANT:
Please note "=" character at the begining of body content. It
must be there.
Request
POST https://rexapi.local.gryphtech.com/api/v1/oauth/ValidateClient?integratorID=1005001 HTTP/1.1 Accept: application/xml; charset=utf-8 Content-Type: application/x-www-form-urlencoded =client_id%3D10D35802-C92A-42B3-88FC-A4489A3CD619%26secret%3D666E465A-6012-45B9-AA1E-ADDD728F61DE
Response XML
HTTP/1.1 200 OK Content-Type: application/xml; charset=utf-8 <ClientValidationResponse> <clientstatus>Valid_Client</clientstatus> <expires_in>172800</expires_in> </ClientValidationResponse>
Response JSON
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"clientstatus": "Valid_Client",
"expires_in": 172800
}
- clientstatus
- Possible values: Valid_Client or Unauthorized_Client
- expires_in
- This represent the life span of the authorization token. Its value is in seconds. In our example, 172800 seconds = 48 hours. This means that this token will expire (no longer be valid) after 48 hours from the moment it was generated.
Use authentication in your API calls
All API request to resources must be authenticated. For this, we use the Authorize header. It should look like this:
Authorization: OAUTH oauth_token="pfl4PLrrHKChIRoDS2O9Wfoyr1yjKgbEjCxk+adBohqos93Ev0cbSBC", api_key="10D35802-C92A-42B3-88FC-A4489A3CD619"
- oauth_token
- This is the authorization token obtained with method oauth/token
- api_key
- This is the application key preassigned to you by Gryphtech
Request example
GET https://rexapi.local.gryphtech.com/api/v1/integrator/1005001/offices HTTP/1.1 Authorization: OAUTH oauth_token="pfl4PLrrHKChIRoDS2O9Wfoyr1yjKgbEjCxk+aO7LS6zs3AQ=", api_key="10D35802-C92A-42B3-88FC-A4489A3CD619" Accept: application/xml; charset=utf-8