Developer APIs

Introduction

Warpwire's technology runs on its own RESTful API.

This guide is intended for software developers and IT administrators who want to provide deep systems integration with Warpwire. It provides general information on the programmatic creation of objects via the REST API, data conventions, and integrating and merging with existing datasets. Understanding the basic Warpwire conventions will help you provide an optimal integration experience for your users.

This document is divided into sections that reflect each of the external data management layers that Warpwire provides. Warpwire leverages web standards for API communication, uses SSL for all data transmission and encryption, and provides access control levels for every API call.

Warpwire also integrates with an organization's Single Sign-On (SSO) system to provide both user authentication and authorization. Specifics regarding SSO integration are provided in additional specification guides and are outside the scope of this document. Warpwire uses a REST-ful style interface utilizing both REST nouns and verbs.

Additional Resources

  Warpwire Guides and Videos

  Warpwire Plugins available on GitHub

  PDF: Warpwire Reporting API Reference Guide v1.0

  PDF: Warpwire Group Import API Reference Guide v2.0

  PDF: Warpwire Hotspot Analytics API Reference Guide v1.0

ConventionsConventions

Warpwire uses a few simple conventions throughout the entire API to ensure that operations are both consistent and predictable. There are a few API calls that deviate from these conventions — these deviations are explicitly noted. The following section lists the Warpwire nomenclature that is used throughout this document:

UUID — All objects are automatically assigned a Universally Unique Identifier (UUID). It is through this value that all objects are accessed. A UUID is guaranteed to be unique for every object within an organization and is analogous to a primary key.

Collection — A set of objects is stored in a collection. A collection can store both objects and additional collections. A collection is also commonly referred to as a "Media Library" in other end user documentation, however these terms are synonymous. Access control and permissions are managed on a collection basis where every item within a collection maintains the same permissions (see Permission section). If an object does not exist within a specified collection a 404 Not Found response is returned (see HTTP Response Codes for additional information).

Example

If object A is a member of two different collections, C1 and C2, there is no guarantee that object A's permissions will be the same in both C1 and C2. However, you are guaranteed that every object within C1 and C2 will have the same base permissions.

UUID Specification — All UUIDs provided are assigned by the API upon object creation and follow the RFC 4122 version 5 specifications. All UUID's are in hexadecimal format and follow the pattern {8}-{4}-{4}-{4}-{16}, with dashes being optional. Most API GET request returns the object UUID as a response parameter.

Authentication Tokens — A token is expected to be supplied as a header request for every API call that is not public. If you make a private API call and do not provide an Authorization: OAuth header and accompanying token, the request will fail and return 401 Not Authorized. Please note that all tokens have expirations and must either be renewed or re-issued upon session expiration, user sign out, or token invalidation.

API FormatAPI Format

Most API calls follow this convention:

{ACTION}/c/{COLLECTION_UUID}/o/{OBJECT_UUID}

All requests that are non-public expect an Authorization: OAuth header. The API returns all data as an 8-bit UTF JSON encoded string. It is suggested that you also ensure that all input data is encoded in UTF-8 format to ensure maximum data consistency. Below is an example of a typical POST command using CURL.

Example

curl https://api.example.com/api/describe/c/ABCDEF-1234-CDEF-5678-ABCDEF0123456789/o/CCCBBB-1234-CDEF-5678-ABCDEF0123456789/ -H 'Authorization: OAuth c4eFFFwnmnGIbud1Bxyyzmg4yHmD9D92DJhlWNIib' -X POST -d "title=My+first+title" –v

REST ConventionsREST Conventions

Warpwire utilizes most of the HTTP methods including GET, POST, PUT, DELETE, OPTIONS, and HEAD. For clients that do not support a specific method such as DELETE or PUT, you should use the POST method and include a POST data variable named "_METHOD" with the value being the type of method in question (see the example below). Alternatively, you can also use the X-HTTP-Method-Override header directive to specify the missing method. Warpwire recommends that you use the CURL library as it supports the entire set of HTTP methods.

Example

HTTP/1.1 {URL} POST

<input type="hidden" name="_METHOD" value="DELETE">

Warpwire uses the HTTP methods as follows:

GET — Returns JSON-encoded data for the supplied URL. The GET method expects the URL to include both the complete path for the resource and the identifying resource information (e.g. collection UUID). The GET command will always return a JSON-encoded object or the empty set if no data is returned. It also returns a corresponding HTTP response code that indicates the status of the transaction (i.e. 200 OK indicates a successful request and 400 Bad Request indicates a malformed request). Please see the HTTP Response Codes section for more information.

PUT — Used to create a new object. This method will return a HTTP 201 Created response upon the successful creation of a resource. Additionally, if the user does not have permission to issue the PUT call for a particular collection, the call will return a HTTP 403 Forbidden header. Please note that since you cannot manually assign a universally unique identifier for an object, re-issuing a PUT request will result in the creation of a new object.

POST — Used to update any existing object. This method will return a HTTP 202 Accepted response upon the successful modification of a resource. The POST command expects the URL to only contain information necessary to access the resource, such as the collection UUID and object UUID. All other parameters must be specified in the POST data fields. Note that some parameters can only be issued via the initial PUT request and cannot be changed via a POST request. If the user does not have permission to issue the POST command for a particular collection, the method will return a HTTP 403 Forbidden response.

DELETE — Removes a resource. This method will return a HTTP 200 OK response upon the successful deletion of a resource. The DELETE method is not available for most API calls. If the user does not have permission to issue the DELETE command for a particular collection, the method will return a HTTP 403 Forbidden response.

OPTIONS — Return 200 OK for most calls that issue this request. This call is used in conjunction with all pre-flight Cross-origin resource sharing (CORS) calls. If you are using the API via CURL (or other command line tools) it is not necessary to supply the OPTIONS call. For time consuming operations such as uploading, the OPTIONS method will return proper response information that should be used to determine if the operation should proceed (e.g. the user is not currently authenticated to perform the request). If you are calling the API via AJAX requests within a web browser, you must comply with all CORS requirements. Therefore, you must ensure that the server making the requests has been added to the allowed list of servers that may perform a Access-Control-Allow-Origin request.

DescribeDescribe

Describe is the most basic and important Warpwire API call. You can think of a describe API call as a mobile phone's address book that provides basic metadata and routing information for a contact. The describe call is public and does not require any user authentication (nor the need to supply the Authorization: OAuth header). However, a public request will only a return a limited subset of data about an object while an authenticated call will return the complete record.

GET Method:

/api/describe/c/[collection_uuid]/o/[object_uuid]/

Request — The GET request must be in the following format.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid object UUID resource.

Response — For any GET request the following information can be returned in a JSON formatted object.

Attribute Description
type A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
images An array of images that accompany the object. Please note that the images array may be an empty set.
images.thumbnail A 128x128 pixel image of the resource (if available).
images.square A 512x512 pixel image of the resource (if available).
images.large A 1280x760 pixel image of the resource (if available).
public Should this resource be available to the public? The values can include either "true" or "false". Default value is "false".
metadata An array of metadata associated with the object. This could include additional information such as duration, or the empty set.
description Textual description of the object. This may be blank.
properties An array of properties that accompany the object. This could be an empty set.
uuid The universally unique identifier of the object.
userId Identifier of user who created the resource. This information is not informative without performing an additional user API call.
authenticated Indicates if the current user is authenticated. Value is either "true" or "false".
permLink A permanent shortened URL that a user can access the resource.
created An Epoch timestamp of the date the object was created.
modified An Epoch timestamp of the date the object was modified.

PUT Method:

/api/describe/c/[collection_uuid]/o/0/

Request — Adds an object to an existing collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information may be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource. If the resource is 0 a new collection will be created.
type (required) A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
public Should this resource be available to the public? The values can include either "true" or "false". Default value is "false".
description Textual description of the object. This may be blank.
duration The duration of the media object in seconds.

Response — The following response is returned for the PUT request as a JSON encoded object.

Attribute Description
uuid The universally unique identifier of the object.

POST Method:

/api/describe/c/[collection_uuid]/o/[object_uuid]/

Request — Updates an object. Any parameter not specified in the URL above must be submitted as a POST data field. For any POST request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid object UUID resource.
type (required) A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
public Should this resource be available to the public? The values can include either "true" or "false". Default value is "false".
description Textual description of the object. This may be blank.
duration The duration of the media object in seconds.

Response — The following response is returned for the POST request as a JSON encoded object.

Attribute Description
uuid The universally unique identifier of the object.

UserUser

The user API call is used to get information about a particular user. The user API call requires user authentication and is not public. Additionally, based on the user’s permission level, a subset of information regarding the user may be returned.

GET Method:

/api/user/c/[collection_uuid]/o/[user_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) A valid user identifier. If this value is 0, it will return the user information for the currently authenticated user.

Response — For any GET request the following information can be returned.

Attribute Description
firstName123 The requested user’s first name.
lastName123 The requested user’s last name.
userId12 The requested user’s identifier.
uniqueId12 The requested user's SSO unique identifier.
{parameters} Additional parameters that are stored about the user.

1 — Provided to the currently authenticated user if they are making a self request
2 — Provided to the an administrator of a collection the userId is a member
3 — Provided to all authenticated and authorized users

POST Method:

/api/user/c/[collection_uuid]/o/[user_id]/

Request — Updates a user. For any POST request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) The requested user’s identifier. If this value is 0, the uniqueId POST data field is required.
firstName The requested user’s first name.
lastName The requested user’s last name.
uniqueId (conditional) The requested user’s SSO unique identifier. Required if the user_id field is 0.

Response — For any POST request the following information is provided.

Attribute Description
userId The user identifier.

PermissionPermission

The permission API call returns information regarding access control levels. The permission API call requires authentication.

GET Method:

/api/permission/c/[collection_uuid]/o/[user_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) A valid user identifier. If this value is 0, it will return user information for the entire collection.

Response — For any GET request the following information can be returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
firstName The requested user’s first name.
lastName The requested user’s last name.
userId The requested user’s identifier.
uniqueId The requested user's SSO unique identifier.

PUT Method:

/api/permission/c/[collection_uuid]/o/[user_id]/

Request — Adds a user to a collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (conditional) The requested user’s identifier. If this value is 0, the uniqueId PUT data field is required.
uniqueId (conditional) The requested user's SSO unique identifier. Required if the user_id is 0.
level The permission level to assign to the user. Possible values are "none", "view", or "admin". Default value is "view".

Response — For PUT requests a HTTP 201 status code is returned. There is no other information provided in the response.

POST Method:

Identical to the PUT Method. See above.

DELETE Method:

/api/permission/c/[collection_uuid]/o/[user_id]/

Request — Removes a user from a collection. For any DELETE request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
user_id (required) A valid user identifier.

Response — For DELETE requests a HTTP 200 status code is returned. There is no other information provided in the response.

InfoInfo

The info API call returns information for objects. The info API call requires authentication.

GET Method:

/api/info/c/[collection_uuid]/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.

Response — For any GET request the following information can be returned.

Attribute Description
type A textual version of the type of resource. This value will be "info".
owner An array containing information about the owner of the object.
owner.userId The object owner’s user identifier.
owner.firstName The object owner’s first name.
owner.lastName The object owner’s last name.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
description The description of the object. The description may be blank.
created An Epoch timestamp of the date the object was created.
modified An Epoch timestamp of the date the object was modified.
properties An array of properties that accompany the object. This could be an empty set.
uuid The universally unique identifier of the object.
fileType A textual version of the type of file. This could include "catalog", "video", "audio", "file", etc.
duration The duration of the media object in seconds.

POST Method:

/api/info/c/[collection_uuid]/o/[user_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.
title The title of the object. A title may be blank or can be up to 255 characters in length.
description The description of the object. The description may be blank.

Response — For POST requests a HTTP 202 status code is returned. There is no other information provided in the response.

EmbedEmbed

The embed API call returns information regarding embedding an object. The embed API call requires authentication.

GET Method:

/api/embed/c/[collection_uuid]/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.

Response — For any GET request the following information can be returned.

Attribute Description
type A textual version of the type of resource. This value will be "embed".
properties An array of properties that accompany the object. This could be an empty set.
properties.link URL of object.
properties.iframe Iframe embed code for the object.
properties.script JavaScript embed code for the object.

VideoVideo

The video API call returns information about a video object. The video API call requires authentication.

GET Method:

/api/video/c/[collection_uuid]/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_id (required) A valid object UUID resource.

Response — For any GET request the following information can be returned.

Attribute Description
type A textual version of the type of resource. This value will be "video".
properties An array of files that accompany the object. Please note that the files array may be an empty set.
files.format The format of the video file. This can include "hls", "smil", or "mp4".
files.url The URL of the video file.
files.properties An array of properties for the video file. Please note that the properties array may be an empty set.
files.properties.thumbnail The thumbnail image for the Web Video Text Tracks (VTT) file for the video.
images An array of images that accompany the object. Please note that the images array may be an empty set.
images.thumbnail A 128x128 pixel image of the resource (if available).
images.square A 512x512 pixel image of the resource (if available).
images.large A 1280x760 pixel image of the resource (if available).
uuid The universally unique identifier of the object.

AuthenticateAuthenticate

The authenticate API call returns information regarding authentication of users. The authenticate API call does not require authentication.

GET Method:

/api/authenticate/

Request — For any GET request no further information needs to be provided.

Response — For any GET request the following information is returned.

Attribute Description
type A textual version of the type of resource. This value will be "authenticate".
authenticated Is the current user authenticated? The values can include either "true" or "false". If you do not provide an authenticated user, the result will always be "false".

CatalogCatalog

The catalog API call returns information regarding all objects that exists within a collection. The catalog API call requires authentication.

GET Method:

/api/catalog/c/[collection_uuid]/o/[object_uuid]/

Request — For any GET request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid object UUID resource.
ts The Epoch timestamp. If provided, only objects that have been updated since the timestamp will be returned. Cannot be 0.
completeRecords The number of complete records to return. If not provided, all returned objects will be complete describe objects.

Response — For any GET request the following information is returned. This call will return an array of objects that contain the properties specified below, or the empty set.

Attribute Description
ts The Epoch timestamp at which the request occurred.
list An array of objects which exhibit the properties below, or the empty set.
type A textual version of the type of resource. This could include "catalog", "video", "audio", "file", etc.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
images An array of images that accompany the object. Please note that the images array may be an empty set.
images.thumbnail A 128x128 pixel image of the resource (if available).
images.square A 512x512 pixel image of the resource (if available).
images.large A 1280x760 pixel image of the resource (if available).
description Textual description of the object. This may be blank.
properties An array of properties that accompany the object. This could be an empty set.
uuid The universally unique identifier of the object.
userId Identifier of user who created the resource. This information is not informative without performing an additional user API call.
authenticated Indicates if the current user is authenticated. Value is either "true" or "false".
created An Epoch timestamp of the date the object was created.
modified An Epoch timestamp of the date the object was modified.

PUT Method:

/api/catalog/c/[collection_uuid]/o/[object_uuid]/

Request — Adds an object to a collection. Any parameter not specified in the URL above must be submitted as a PUT data field. For any PUT request the following information can be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid collection or object UUID resource.

Response — For PUT requests a HTTP 201 status code is returned. There is no other information provided in the response.

POST Method:

Identical to the PUT Method. See above.

DELETE Method:

/api/catalog/c/[collection_uuid]/o/[object_uuid]/

Request — Removes an object from a collection. For any DELETE request the following information must be provided.

Attribute Description
collection_uuid (required) A valid collection UUID resource.
object_uuid (required) A valid collection or object UUID resource.

Response — For DELETE requests a HTTP 200 status code is returned. There is no other information provided in the response.

ContributeContribute

The contribute API call returns information regarding group membership of an object. The contribute API call requires authentication.

GET Method:

/api/contribute/o/[object_id]/

Request — For any GET request the following information must be provided.

Attribute Description
object_id (required) A valid object UUID resource.

Response — For any GET request an array of the following information can be returned.

Attribute Description
uuid The universally unique identifier of the media library.
title The title of the resource. A title may be blank or can be up to 255 characters in length.
member Whether or not the object is a member of the corresponding media library.

HTTP Response CodesHTTP Response Codes

All calls to the REST API will always return a standard HTTP 1.1 status code as a response. The status codes that the Warpwire API will return are listed below.

Status Code Description
200 OK. The request is successful.
201 Created. The resource has been successfully created.
202 Accepted. The resource has been successfully modified.
302 Temporarily redirected. The resource has moved and you will need to follow the URL for the updated resource.
400 Bad Request. The API call could not be processed because one or more input parameters are not valid. Please confirm all parameters are correct.
401 Unauthorized. The user needs to authenticate to view a resource. Please direct the user to the authentication endpoint.
403 Forbidden. The user does not have access to the requested resource. They must be added to the appropriate collection or group.
404 Not Found. The resource could not be located or the API method could not be found.
409 Conflict. There is a conflict that prevents an object from being updated or created. The error message should contain additional information.
500 Internal Server Error. These errors are not generated by the API directly and indicate an issue with the server. Please contact Warpwire for an appropriate resolution.
501 Not Implemented. You are requesting an API call that has not yet been implemented. Please use a different method.
503 Service Unavailable. The Warpwire servers are currently unavailable to fulfill your request. Please wait a few moments and try your request again.

Connecting Warpwire and Third Party Applications using OAuth 2.0Connecting Warpwire and Third Party Applications using OAuth 2.0

This guide will explain how OAuth 2.0 can be leveraged to allow your third party application to make requests to Warpwire's API on behalf of the end user at the institution your application is partnering with.

OAuth 2.0 allows third party applications to request authorization to act on a user's behalf, without the user having to expose their username and password. In this way, once authorization had been granted, your client application can make requests to Warpwire's API on behalf of the authorized user.

The client application will direct the end user to a Warpwire Authorization page, where the user can approve or deny the authorization request using their institutional SSO login credentials. The user will then be redirected to a callback URL provided by the client application. If the authorization request is approved, the client application will receive an access_token. If the user approved long-term offline access by your application, then you will also receive a refresh_token.

This access_token acts as a temporary password, granting the client application limited access to "log in" as a user and act on their behalf. Tokens are time limited. If a token expires, the client application will either have the end user re-authorize, or use a refresh_token to get a new, unexpired access_token.

This process ensures that end users have control over how and when they grant authorization to outside applications. OAuth provides a simple way for third party applications to interface with any Warpwire user, without having to understand each institution's custom SSO integrations.

Workflow

Begin by registering your application with the administrators of Warpwire at the institution you're interfacing with. After registering, you'll receive a client_id and client_secret, which you'll use to make requests.

At registration, you'll need to provide all possible callback URLs, so that Warpwire can match them against the redirect URLs provided in your authorization requests for users.

You'll link your users to the authorization endpoint, where they'll log in, if they haven't already. When you send the user to the endpoint, be sure to set the following parameters:

response_type = code
client_id = the id you were given at registration
redirect_uri = one of the URLs you provided at registration
access_type = set to offline if you want access to refresh_token
state = a unique string used to verify state consistency, to mitigate CSRF attacks

Example

HTTP/1.1 302 Found

Location: https://example.warpwire.com/api/oauth/authorize?response_type=code&client_id=client123&redirect_uri=http://client.com/callback&state=EwLhomzP42dOss6x

They'll then see the authorization request form, and either approve or deny the authorization request. The request form will indicate the name of the application requesting authorization, which permissions the application is requesting.

Once the form is submitted, the user will be redirected to the redirect_uri provided by the client application at registration, using 302 FOUND redirect.

The response, if valid, should include the same state value as in the request parameter. If the state does not match, or is invalid, you should halt the workflow - do not continue.

If the user granted authorization, the client will receive a code, which can be exchanged for an access_token, and state which, as stated above, should match the value passed in the request.

GET /cb?code=KI3zGhVdDzFWwkOa&state=EwLhomzP42dOss6x HTTP/1.1

Host: client.example.com

If the user denied the authorization request, check the response for error and error_description, along with state (which should still match the request parameter!)

GET /cb?error=access_denied&error_description=description+of+error+here+&state=EwLhomzP42dOss6x HTTP/1.1

Host: client.example.com

If access was granted, next exchange the code for an access_token by making a request to the Warpwire API. Your request should include the following parameters:

grant_type = set to authorization_code
code = the code you received in the authorization response
redirect_uri = must match a URL given in authorization request, or token will not be given
client_id = the ID you received at registration
client_secret = the secret you receives at registration

Example
POST /api/oauth/access_token HTTP/1.1
Host: example.warpwire.net
Content-Type: application/json
{
"grant_type": "authorization_code",
"code": "KI3zGhVdDzFWwkOa",
"redirect_uri": "https://client.example.com/callback",
"client_id": "client123",
"client_secret": "2Oer67X5KnbmNylo"
}

You'll receive a response from Warpwire that includes the following parameters:

token_type = bearer
access_token = unique string used to authenticate API requests on behalf of the user
expires_in = number of seconds access_token will remain valid
refresh_token = if offline access was granted, you'll have a string here which can be used to get a new access_token when the current one expires

Example

HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"access_token": "PWB0Wm97irdYcAye",
"expires_in": 7200,
"refresh_token": "TE1Eduhx5lStSldE"
}

With your access_token in hand, you can now make API requests on behalf of the authorized user. Pass the access_token via the authentication header.

Example
GET /api/oauth/authorize/ HTTP/1.1
Host: example.warpwire.com
Authorization: Bearer PWB0Wm97irdYcAye

When, after the allotted seconds have passed, the access_token expires, you will receive a 401 Unauthorized error from Warpwire, along with an "invalid credentials" message, or similar.

Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Invalid credentials"
}

To re-authorize, either go through the authorization process again, or if you have a refresh_token, make a refresh request, using the following parameters:

grant_type = refresh_token
refresh_token = the token you received
client_id = the id you were given at registration
client_secret = the secret you were assigned at registration

Example
POST /api/oauth/access_token HTTP/1.1
Host: example.warpwire.net
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "TE1Eduhx5lStSldE",
"client_id": "client123",
"client_secret": "2Oer67X5KnbmNylo"
}

If your request is successful, you'll receive a new access_token and refresh_token in Warpwire's response. Please note that the refresh_token can only be used once. Make sure to store the value, or you'll have to begin the authorization process again. Once a refresh_token is used, it becomes invalid. It will be replaced with a new refresh_token.

The response will include the following parameters:

token_type = bearer
access_token = the new token you can use to authenticate API requests
expires_in = number of seconds the token will be valid
refresh_token = a new token that overwrites the one made in the original refresh request

Repeat the refresh request process as needed, as each refresh_token can be used only once.

Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"access_token": "PWB0Wm97irdYcAye",
"expires_in": 7200,
"refresh_token": "TE1Eduhx5lStSldE"
}