Most Plotto API requests require authorization. This section describes how to use authentication to obtain an access token to use for authorization.


Authorization follows the OAuth 2.0 specification with the password grant type. This means that two steps are required to make a request with authorization:

  1. A request is made to the authentication endpoint, where your Plotto username and password are passed in as parameters. An access token is returned.
  2. The access token is used in the Authorization header after the word “Bearer” or as an access_token query parameter.

For example, if your access token were the string "4c3179a5fcb25207d2e2d626e93f5", then for each request that requires authorization, you use the following header:  

                   Authorization: Bearer 4c3179a5fcb25207d2e2d626e93f5


Alternatively, you can specify the access token using a query parameter called access_token. For example, a call to return a list of projects would look like this:


         GET https://api.plotto.com/project/list?access_token=4c3179a5fcb25207d2e2d626e93f5


The access token will expire after a set period of time that is specified in the response from the authorization request. It is typically 60 minutes. After this, you must use the refresh token in the response to get a new access token.


Note. Not all API requests require authorization. If the documentation does not indicate that you need a header with an access token, then it is not required.


Authentication Request

Uses credentials to authenticate and return an access token.


URL

/oauth/token


Method

POST


Headers

Header

Value

Required

Content-Type

Application/json

Required


POST Body

A JSON object with the following elements:


Element

Description

Type

Required

grant_type

The value password

String

Required

client_id

The value 0

String

Required

client_secret

The value #

String

Required

username

Your Plotto username

String

Required

password

Your Plotto password

String

Required



Sample Request

POST https://api.plotto.com/oauth/token

Headers:
  Content-Type: application/json

POST Body:
{
  "grant_type": "password",
  "client_id": "0",
  "client_secret": "#",
  "username": "rachel@example.com",
  "password": "mypassword"
}

 


Response

If successful, it will return JSON with the following elements.


Element

Description

Type

access_token

The access token to use for authorization

String

refresh_token

The token to use for refreshing when the existing access token expires

String

expires_in

The amount of time, in seconds, when the token expires

Integer

user

Information about the user logging in

A user object (see table below)

token_type

The value Bearer

String


The user object contains these elements:

Element

Description

Type

name

The account holder’s name

String

email

The account holder’s email, which is the username

String

admin

true if the user has administrative privileges

Boolean

youTubeAuthorized

true if the user has authorized a YouTube account

Boolean



Sample Response

{
  "access_token": "7e1d5926c52b23027c288f463520362c250c0173cc",
  "refresh_token": "939d221e7555f0b19c7f176b62085cea25e2b589b",
  "expires_in": 3600,
  "user": {
  "name": "Peter Gruenbaum",
  "email": "peter@sdkbridge.com",
  "admin": false,
  "youTubeAuthorized": true
  },
  "token_type": "Bearer"
}

 


Token Refresh Request

Returns a new access token without requiring the sending of credentials.


URL

/oauth/token


Method

POST


Headers

Header

Value

Required

Content-Type

Application/json

Required


POST Body

A JSON object with the following elements:

Element

Description

Type

Required

grant_type

The value refresh-token

String

Required

client_id

The value 0

String

Required

client_secret

The value #

String

Required

refresh_token

The refresh token from the authentication response

String

Required


Sample Request

POST https://api.plotto.com/oauth/token

Headers:
  Content-Type: application/json

POST Body:
{
  "grant_type": "refresh_token",
  "client_id": "0",
  "client_secret": "#",
  "refresh_token": "939d221e7555f0b19c7f176b62085cea25e2b589b"
}

 


Response

If successful, it will return JSON with the following elements.


Element

Description

Type

access_token

The new access token to use for authorization

String

refresh_token

The new token to use for refreshing when the existing access token expires

String

expires_in

The time, in seconds, when the token expires

Integer

user

Information about the user logging in

A user object (see table below)

token_type

The value Bearer

String


The user object contains these elements:

Element

Description

Type

name

The account holder’s name

String

email

The account holder’s email, which is the username

String

admin

true if the user has administrative privileges

Boolean

youTubeAuthorized

true if the user has authorized a YouTube account

Boolean


Sample Response

{
  "access_token": "f95237b6a7a61bc0fc288f463520362c250c0173cc",
  "refresh_token": "9b33cf503cc98677f176b62085cea25e2b589b",
  "expires_in": 3600,
  "user": {
  "name": "Peter Gruenbaum",
  "email": "peter@sdkbridge.com",
  "admin": false,
  "youTubeAuthorized": true
  },
  "token_type": "Bearer"
}