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:
Authorization Code
Section 4.1Refresh token
Section 6Client Credentials
Section 4.4Device flow
https://developers.google.com/identity/protocols/OAuth2ForDevicesResource Owner Password
Section 4.3
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:
- EASI'R user is redirected to
auth.easir.com
, with the application's client ID and a refresh token - The user accepts the request for authorization, and is redirected back to the redirect URI with an auth code
- 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 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
.
API URL
The base URL for the API is https://api.easir.com
.
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.