Authentication

Authentication APIs

Packly REST API uses the OAuth 2.0 protocol to authorize calls. OAuth 2.0 is an open standard that many companies use to provide secure access to protected resources.

If you want more information about OAuth 2.0 protocol please refer to the following resources:

client ID and secret will be requested for both sandbox and live environments. You’ll need to pass these credentials to the Authorization header in order to obtain an access token and to be able to call Packly’s API.

Access, therefore, takes place through the so-called bearer tokens. They will be used to perform REST API requests. Bearer tokens shall enable you to complete actions on behalf and with the approval of the resource owner.

Note: The client ID and secret are different for your sandbox and live environment.

How to get the access token

  • URL: /v1/oauth2/token
  • Method: POST
  • Header: Authorization. To make a good request and get the access token you need to set the Authorization header with Basic authentication and use as username and password your client ID and secret respectively
  • URL params: none
  • Data params
    • grant_type: specifies the type of grant being requested by the application. At this time, only client_credentials is allowed
    • scope: the scope represents the resource api that you are authorized to use. At this time, only external is allowed
  • Success Response: response will contains a bearer access token indicated by token_type of Bearer and its life time expressed in seconds on expires_in
  • Error response: Errors

Examples

Authentication request

POST /v1/oauth2/token HTTP/1.1
Host: api.packly.io
User-Agent: My Packy User Agent
Authorization: Basic eHZ6MWV2R ... o4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip
 
grant_type=client_credentials
scope=external

Authentication response

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140
 
{"token_type":"bearer","access_token":"AAAA%2FAAA%3DAAAAAAAA","expires_in": 3600}

Access token

The access token is a credential that can be used by a client to access an API.

It can be any type of token (such as an opaque string, or a JWT) and is meant for an API. It's purpose is to inform the API that the bearer of this token has been authorized to access the API and perform specific actions (as specified by the scope that has been granted).

The access token should be used as a Bearer credential and transmitted in an HTTP Authorization header to the API.

{
  "access_token": "0ButNsIhWFngHJ8 ... 1N6nOzmvYPZlmmVI8KbDZE0NOZJHjUAi",
  "expires_in": 3600,
  "token_type": "Bearer"
}

In the success response of the authentication request the access_token field contains a bearer token indicated by token_type of Bearer. Access token has a finite lifetime. The field expires_in express the lifetime of the access token in seconds. You need to request a new access token once its life has expired.

Authenticate HTTP request

Every HTTP request to Packly APIs need to be authenticated using access token. To do that you need to include the bearer token on the Authorization header with the Bearer authentication scheme as repoted below:

Authorization: Bearer eHZ6MWV2R ... o4OERSZHlPZw==