Requesting an authorization code
To request an authorization code you need to provide an API Key, an API Secret, a callback URL and a scope. You should always use the value public_api for scope.
SkyVault will ask the user for their userid and password to grant or deny access to resources for your application. If they grant access, then SkyVault will invoke the callback URL with the authorization code.
Exchanging the authorization code for an access token
Once the application has an authorization code, it can exchange this for an access token. Note that once the application has an authorization code, it has 10 minutes to exchange it. After that, the authorization code is invalid and the application must request a new one.
The application will receive a JSON response body as follows:
{
"access_token":"87727764-3876-43b9-82a1-1ca917302ce5",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"596f6074-f432-4aeb-a162-8196213c659c",
"scope":"public_api"
}
The following table explains the response properties :-| Property | JSON Type | Description |
|---|---|---|
| access_token | string | An access token that can be used to make authenticated calls using the SkyVault API for one hour. |
| token_type | string | The type of token. |
| expires_in | number | The number of seconds the access token will be valid for. SkyVault will issue access tokens valid for one hour. |
| refresh_token | string | Once the access token expires, the application must get a new access token using this refresh token. The refresh token is valid for seven days. |
| scope | string | Always use public_api as the value of scope. |
The access token can be used to make authenticated calls using the Client API for one hour. After that period, the application must get a new access token using the refresh token.
Using the access token
The application now has an access token, and can use it to make API calls.
The preferred method to pass the access token to SkyVault is to include it in the HTTP request header in the Authorization field in the following format:
Value: Bearer [your access token]
This is a an example:
Bearer d1358c05-6564-4086-94b6-a7e14ce3490
After an API call the application will receive a JSON response body such as the following:
{
"list" : {
"pagination" : {
"count" : 2,
"hasMoreItems" : false,
"skipCount" : 0,
"maxItems" : 100
},
"entries" : [ {
"entry" : {
"site" : {
"id" : "general-test-site",
"title" : "General Test Site",
"visibility" : "PRIVATE",
"description" : "Test Site"
},
"id" : "general-test-site",
"role" : "SiteCollaborator"
}
}, {
"entry" : {
"site" : {
"id" : "fred-bloggs-yourcompany-com",
"visibility" : "PRIVATE",
"description" : "Fred Bloggs's private home site."
},
"id" : "fred-bloggs-yourcompany-com",
"role" : "SiteManager"
}
} ]
}
}