Authorization#

AdServer authorizes API users with Bearer Token (JWT). Access token is generated according to OAuth2. AdServer has a built-in OAuth2 server thanks to Laravel Passport.

AdServer supports three methods of acquiring an access token:

  • personal access token - for users which want to interact directly with API, prepare machine access, e.g. third party integrations

  • authorization code grant - for server applications with user interaction, e.g. AdController

  • client credentials grant - for machine access, e.g. maintenance

To authorize, token must be passed in HTTP Authorization header.

Authorization: Bearer <ACCESS_TOKEN>

Some methods use CLIENT_ID and CLIENT_SERVER in requests. These credentials are generated by AdServer’s operator. They should be distributed and stored in a secure way.

Personal Access Token#

Personal Access Token can be used by user to directly interact with API. Token can be generated in AdPanel by authenticated user.

To create a token:

  1. Log in to AdPanel

  2. Go to Account Settings page

  3. Scroll down to Access tokens section

  4. Input name. Name is only for your convenience

  5. Select scopes. Good practice is to choose as few privileges as needed

  6. Click [Create] button

  7. Copy displayed access token

Token is long-lived, but can be revoked in case of compromise. To revoke a token go to Account tokens section, find wanted token and click [Delete] button next to it.

Authorization code grant#

Below is the sample flow in which AdController is the client server. This flow is divided into sections but represents single authentication process. Diagram could be simplified when user interacts with AdPanel and is still logged in. In this situation user does not have to log in once again.

skinparam monochrome true actor "User" as user participant "AdController" as adcontroller participant "AdPanel" as adpanel participant "AdServer" as adserver ==Fetch data (no token)== user -> adcontroller: Open page adcontroller -> adserver: Fetch data adserver -> adcontroller: Unauthenticated 401 ==Fetch code== adcontroller -> adserver: Fetch code adserver -> adpanel: Display log in form adpanel -> user: Log in form user -> adpanel: Log in credentials adpanel -> adserver: Log in adserver -> adpanel: Do redirect adpanel -> adserver: Redirect adserver -> adcontroller: Code ==Fetch access token== adcontroller -> adserver: Fetch token adserver -> adcontroller: Token ==Fetch data (token)== adcontroller -> adserver: Fetch data adserver -> adcontroller: Data adcontroller -> user: Display page

POST /auth/login#

Logs user in to the AdServer. Returns API token.

Status Codes:
Request JSON Object:

  • email (string) – user’s e-mail

  • password (string) – user’s password

Response JSON Object:

  • apiToken (string) – API token

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    ...
    "apiToken": "WQQ6KU37jqgsnamUhkMRzpMmyY44C8c4db7i7HFeRC5xJQTNaVtrWRaH8YxQ",
    ...
}
GET /auth/authorize#

Generates authorization code.

Request Headers:

  • Authorization – authorization header should contain API token Bearer <API_TOKEN>

Status Codes:
Query Parameters:

  • client_id – CLIENT_ID

  • no_redirect – (optional) if present server will return code in body, default action is redirection to callback URI

  • redirect_uri – code callback URI

  • response_type – (constant) code

  • scope – (optional) a space delimited list of scopes

  • state – (optional) CSRF token, will be returned in callback

Response JSON Object:

  • location (string) – callback URI (containing code in query). Present if no_redirect param was set

Example response if no_redirect param is present:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "location": "https://example.com/callback?code=349834jbgtbgbdsd&state=3WJPbImynfEzj34ggMOD7%27hsXrT6Tbjl"
}
POST /oauth/token#

Acquires access token.

Status Codes:
Request JSON Object:

  • client_id (string) – CLIENT_ID

  • client_secret (string) – CLIENT_SERVER

  • code (string) – authorization code from previous request

  • grant_type (constant, string) – authorization_code

  • redirect_uri (string) – code callback URI, must match previous request

Response JSON Object:

  • token_type (constant, string) – “Bearer”

  • expires_in (integer) – token TTL in seconds

  • access_token (string) – token

  • refresh_token (string) – refresh token

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJtZXNzYWdlIjogIkJlZXIgYW5kIGNoZWVzZSBteSBmcmllbmQifQ.A2lO5mO7R8LLAKAXNvmAsVAPOJBc",
    "refresh_token": "d936cc8586ead4b5"
}

Client credentials grant#

This flow consist of single request for token.

POST /oauth/token#

Acquires access token.

Request Headers:
Status Codes:
Request JSON Object:

  • grant_type (constant, string) – (constant) client_credentials

  • client_id (string) – CLIENT_ID

  • client_secret (string) – CLIENT_SERVER

  • scope (string) – (optional) a space delimited list of token’s scopes

Response JSON Object:

  • token_type (constant, string) – “Bearer”

  • expires_in (integer) – token TTL in seconds

  • access_token (string) – token

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJtZXNzYWdlIjogIkJlZXIgYW5kIGNoZWVzZSBteSBmcmllbmQifQ.A2lO5mO7R8LLAKAXNvmAsVAPOJBc"
}