Authentication

About OAuth in EASI'R

The API uses OAuth2 for authentication. The specification can be read here.

EASI'R supports 5 OAuth grant types, described in further detail below:

If you are doing a third-party integration with EASI'R, like creating leads or synchronizing data, you most likely need to use the Client Credentials grant.

Once you have your token, all requests must have a Authorization: Bearer *YOUR_ACCESS_TOKEN* header in all successive requests. You can fetch info about the user with the /me endpoint described below.

The access token expires after 1 hour (3 minutes for the client credentials grant). If you have a refresh token you can use that for the Refresh Token grant and get a new access token.

The refresh token expires after 7 days.

Normal grant types

Authorization Code

This grant type is usually used for giving EASI'R users the ability to allow third-party applications to use their data in EASI'R:

  1. EASI'R user is redirected to auth.easir.com, with the application's client ID and a refresh token
  2. The user accepts the request for authorization, and is redirected back to the redirect URI with an auth code
  3. The auth code can be used to obtain an EASI'R access token.

1. Redirect your user

GET https://auth.easir.com/

To initiate the process from your application, redirect the user to this address.

Query string parameters

  • response_type string
    • Required
    • Must be code
  • client_id string
    • Required
  • redirect_uri string - This is the URI you supplied when creating your application.
    • Required
  • state string - Is an unguessable random string. We recommend that you use this.

2. User accepts the request

POST https://auth.easir.com/token

Query string parameters

  • grant_type string
    • Required
    • Can be one of the following
      • authorization_code
      • password
      • refresh_token
      • client_credentials
      • device_code

Examples of each grant_type is demonstrated below.

Authorization code

POST https://auth.easir.com/token?grant_type=authorization_code

If the user accepts and grant access to their company-account, the user is redirected to the URI you supplied with a code parameter, and a state parameter if available.
If the state is present but not the same as you supplied in step 1, the request has been created by a third party and the process should be aborted.

After being redirected back to your webserver, you can fetch the access token:

Parameters

  • client_id string
    • Required
  • client_secret string
    • Required
  • redirect_uri string - This is the URI you supplied when creating your application.
    • Required

Payload

{
  "client_id": "*YOUR_CLIENT_ID*",
  "client_secret": "*YOUR_CLIENT_SECRET*",
  "redirect_uri": "*REDIRECT_URI*"
}

Response
Status code 200

{
  "access_token": "*ACCESS_TOKEN*",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "*REFRESH_TOKEN*"
}

Client Credentials

POST https://auth.easir.com/token?grant_type=client_credentials

The Client Credentials grant is primarily used for creating integrations with EASI'R for third-party systems, like data synchronization or other forms of programmatic access.

This requires creating a client application in the EASI'R frontend (coming soon) or by requesting a client ID and secret from EASI'R support.

Parameters

  • client_id string
    • Required
  • client_secret string
    • Required

Payload

{
  "client_id": "*CLIENT_ID*",
  "client_secret": "*CLIENT_SECRET*"
}

Response
Status code 200

{
  "access_token": "*ACCESS_TOKEN*",
  "token_type": "Bearer",
  "expires_in": 180
}

Refresh Token

POST https://auth.easir.com/token?grant_type=refresh_token

This grant is for refreshing an expired access token.

Parameters

  • client_id string
    • Required
  • client_secret string
    • Required
  • refresh_token string
    • Required

Payload

{
  "client_id": "*CLIENT_ID*",
  "client_secret": "*CLIENT_SECRET*",
  "refresh_token": "*REFRESH_TOKEN*"
}

Response
Status code 200

{
  "access_token": "*NEW_ACCESS_TOKEN*",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "*NEW_REFRESH_TOKEN*"
}

Trusted/Internal grant types

Resource Owner Password Credentials

POST https://auth.easir.com/token?grant_type=password

Parameters

  • client_id string
    • Required
  • client_secret string
    • Required
  • username string
    • Required
  • password string
    • Required

Payload

{
  "client_id": "*CLIENT_ID*",
  "client_secret": "*CLIENT_SECRET*",
  "username": "*USERNAME*",
  "password": "*PASSWORD*",
}

Response
Status code 200

{
  "access_token": "*ACCESS_TOKEN*",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "*REFRESH_TOKEN*"
}

Device flow

Step 1

POST https://auth.easir.com/token?grant_type=device_code

Parameters

  • client_id string
    • Required
  • client_secret string
    • Required

Payload

{
  "client_id": "*CLIENT_ID*",
  "client_secret": "*CLIENT_SECRET*"
}

Response
Status code 200

{
  "verification_uri": "https://auth.easir.com/token?grant_type=device_code",
  "user_code": 390666,
  "device_code": "E9Hn8O6LcISVC8dvhcDpZlkntbLt5GsmuvtR7eMu",
  "interval": 5
}

Step 2

POST https://auth.easir.com/token?grant_type=device_code

Make a request to EASI'R every interval second.

Parameters

  • client_id string
    • Required
  • client_secret string
    • Required

Payload

{
  "client_id": "*CLIENT_ID*",
  "client_secret": "*CLIENT_SECRET*",
}

Until the user has authorized the device you will get a 400 Bad request response. The code is valid for 10 minutes.

When the user has authorized the device, you will get access token and refresh token in the response.

Response
Status code 200

{
  "access_token": "pBPhxPpDYF3Im7amQmdTPPZqCutuEKcpHh1aL08i",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tbgDaLtsr3Uk3N3hgi6L9VBBJHRvrMRgoLQ95O0Z"
}

When a user is authorizing a device

POST /device-activation

Parameters

  • code integer
    • Required

Payload

{
  "code": 474602
}

Response
Status code 204

Get logged-in user

GET /me

With an access token, you can fetch the details of the user with this endpoint.

Response
Status code 200

{
  "id": 1,
  "first_name": "Doe",
  "last_name": "John",
  "phone_number": "+4588888888",
  "job_title": "Animal",
  "email": "info@easir.com",
  "profile_picture": "http://look-alikes.dk/resized/648efcc8df39e085661c2f528dce7447.jpg",
  "locale": {
    "code": "en-US",
    "language_name": "English",
    "country": {
      "name": "United States",
      "native_name": "United States",
      "code": "US"
    }
  },
  "timezone": {
    "name": "Europe/Copenhagen",
    "offset": 3600
  },
  "company": {
    "id": 1,
    "name": "John",
    "billing": {
      "invoice_email": "info@easir.com",
      "address_1": "Savannah 123",
      "address_2": "Under the tree on the left",
      "zip_code": "4730",
      "city": "Umzimkulu",
      "state": "KwaZulu-Natal",
      "country": {
        "name": "South Africa",
        "native_name": "South Africa",
        "code": "ZA"
      }
    },
    "phone_number": "031 308 7900",
    "website": "https://easir.com",
    "vat": "1234567890123456",
    "timezone": {
      "name": "Africa/Johannesburg",
      "offset": 7200
    },
    "locale": {
      "code": "en-US",
      "language_name": "English",
      "country": {
        "name": "United States",
        "native_name": "United States",
        "code": "US"
      }
    },
    "language": {
      "code": "en",
      "name": "English"
    },
    "currency": {
      "name": "US Dollar",
      "name_plural": "US dollars",
      "code": "USD",
      "symbol": "$",
      "symbol_native": "$",
      "decimal_digits": 2,
      "rounding": 0
    },
    "settings": {
      "b2c": {
        "allow": true,
        "default": true
      },
      "theme": "default",
      "product": {
        "mode": "advanced"
    },
    "default_account_id": null
    },
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2014-01-02 00:11:22"
  },
  "team": {
    "id": 1,
    "name": "Team 1",
    "address_1": "Savannah 123",
    "address_2": "Under the tree on the left",
    "zip_code": "4730",
    "city": "Umzimkulu",
    "state": "KwaZulu-Natal",
    "country": {
      "name": "South Africa",
      "native_name": "South Africa",
      "code": "ZA"
    },
    "phone_number": "031 308 7900",
    "website": "https://easir.com",
    "vat": "1234567890123456",
    "timezone": {
      "name": "Africa/Johannesburg",
      "offset": 7200
    },
    "locale": {
      "code": "en-US",
      "language_name": "English",
      "country": {
        "name": "United States",
        "native_name": "United States",
        "code": "US"
      }
    },
    "created_at": "2014-01-01 12:45:56",
    "updated_at": "2014-01-02 00:11:22"
  },
  "created_at": "2014-01-01 12:45:56",
  "updated_at": "2014-01-02 00:11:22"
}

Requests

All POST and PUT requests MUST have a Content-Type which is set to application/json.

Time and date

All timestamps returned from the API is in the UTC timezone.

It is up to you to convert it to the right timezone.

There is registered a timezone on both the company, the team and the user.

HTTP status codes

The following HTTP status codes, will be the ones we are using, if everything is OK:

200 - OK
201 - OK, created
202 - OK, but queued,
204 - OK, but no content

User types and data sharing

There are 4 different user types - admin, team_admin, group_admin and user.

When you create a company, you will in the same request create an user. This user will have the user type admin.
If you use the team feature, you can have an user in that team with the user type team_admin, and that user can set settings that will only apply to that specific team.
Users will by default be of the user type user, and have no extended rights. A user can later on be promoted to either team_admin or admin.
There must be at least 1 user of the type admin.

Users in teams share data. If you put your teams in a group, they will also be sharing data. Data created by users who are not in a team will be shared with all users.

A team can have specific custom fields, field sorting and relations path details, that will only apply to the users in that team/group.