Authentication

For most routes you will require a valid access token, Parrot supports thepasswordandclient_credentialsgrant types.

Use HTTPS

It is a good practice to use a secure connection for all traffic to and from your API. This is especially important as access tokens are the only thing that a user needs to make authenticated/authorized requests, and protecting them is vital. Check out the OAuth 2 specification for more information on why this is necessary.

Issue a token

To issue a token, make aPOSTrequest to the/auth/tokenendpoint with the corresponding parameters. For example:

POST https://localhost/api/v1/auth/token

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&
client_id=YOUR_CLIENT_ID
&
client_secret=YOUR_CLIENT_SECRET

You will receive a token if the server authorized your request:

{
  "meta": {
    "status": 200
  },
  "payload": {
    "access_token": "eyJhbGciOiJIUzICNiIsInR5cCI6IkpXVCJ9.eyJzdWJUeXBlIjoidXNlciIsImV4cCI6MTQ4NDQwMTExOSwiaWF0IjoxNDg4MzE0NzE5LCJpc3MiOiJodHRw5zovL2dpdGh1Yi5jb20vYW50aG9ueW5zaW1vbi9wYXJyb3QiLCJzdWIiOiJjNzc4NsNkNS04OcM5LTRiYmQtOTZjYy00MmI3ZjZjYWQ2YWIifQ.05l3z4FTLbIJicwxjH-26dsAaMvvQOlDcJ5gIK76W6o",
    "token_type": "Bearer",
    "expires_in": "86400"
  }
}

From now own, simply include the token as a request header for all subsequent requests. Like so:

  Authorization: Bearer YOUR_TOKEN

The 'password' grant type

This grant type is used when authenticating as a user. The user must be already registered. Besides the grant_type parameter, the request must also include the username (the user's email) and the password (the user's password) parameter. For example:

POST https://localhost/api/v1/auth/token

Content-Type: application/x-www-form-urlencoded

grant_type=password
&
[email protected]
&
password=mysecretpassword

The 'client_credentials' grant type

This grant type is used when authenticating as a client application. The client application must have already been registered for a particular project. Besides the grant_type parameter, the request must also include the client_id and the client_secret parameter. For example:

POST https://localhost/api/v1/auth/token

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&
client_id=7f3e7c03-4d9f-4dca-a2a8-9b36bc5c5034
&
client_secret=ta7aba2asd8v!9b36bc5f

Users

Tokens issues with a grant_type of password represent a user. This means that they can access all endpoints that the underlying user is authorized to access. See the Roles section of this documentation for more info.

Client Apps

Tokens issues with a grant_type of client_credentials represent a client application. This means that they can access all endpoints that the underlying client is authorized to access. See the Roles section of this documentation for more info.

Making authenticated requests

Regardless of whether your access token represents a user or a client application, you must include it the same way to interact with the protected API endpoints. Simple add the following header to your requests, replacing the YOUR_TOKEN with your recently issued token:

  Authorization: Bearer YOUR_TOKEN

Token Expiration

As access tokens are the only thing that a user needs to make authenticated/authorized requests, a short validity time is used. Currently it is set to expire after 24 hours of being issued, but it can vary. Be sure to handle token expiration appropriate as you won't be able to make further requests without a valid token. In the future a refresh token will be added to handle this better.