Client ID & Client Secret

Client applications and services must use the client_id and client_secret (found here) to generate a valid access_token. The access_token must then be passed via the HTTP header when invoking any of the REST API Endpoints. All authorization requests are submitted to the REST API Authorize URL/Endpoint.

Client Side Protocol

To send the server authentication credentials, you must use the Authorization HTTP header.

The Authorization header is constructed as follows (after Base64 encoding):

• client_id and client_secret are combined into a string as "your_client_id:your_client_secret" (Note the punctuation mark :, a colon, between the two values).
• The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line.
• The Authorization method and a space, i.e. "Basic ", is then put before the encoded string.

For example, if the client_id is '269a7997-8c8e-4041-a286-531ecee93ad1' and the client_secret is '062f6075-2694-4844-b789-2121ea85b897', the header is formed as follows (after Base64 encoding):

Authorization: Basic MjY5YTc5OTctOGM4ZS00MDQxLWEyODYtNTMxZWNlZTkzYWQxOjA2MmY2MDc1LTI2OTQtNDg0NC1iNzg5LTIxMjFlYTg1Yjg5Nw==

Request (Example)

GET /authorize HTTP/1.1
Host: https://api.equipcalendar.com
Connection: keep-alive
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 Chrome/43.0.2357.124 Safari/537.36
Content-Type: application/json
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Authorization: Basic MjY5YTc5OTctOGM4ZS00MDQxLWEyODYtNTMxZWNlZTkzYWQxOjA2MmY2MDc1LTI2OTQtNDg0NC1iNzg5LTIxMjFlYTg1Yjg5Nw==

Response (Example)

Note: expires_in is returned in seconds

{
  "access_token": "ed10f148-d448-42e1-a8e4-5c60ad35bf28:guid",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "2eb4848a-495e-4446-a421-b0b9603a52z9:guid"
}

After obtaining the access_token from the authentication service, the client application must pass the access_token to the REST API Endpoints in the HTTP header of each request.

HTTP Header

To send the server your access_token, you must use the Authorization HTTP header.

The Authorization header is constructed as follows (after Base64 encoding):

• The access_token is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
• The token_type and a space, i.e. "bearer ", is then put before the encoded string.

For example, if the access_token is 'ed10f148-d448-42e1-a8e4-5c60ad35bf28:guid' and the token_type is 'bearer', the header is formed as follows:

Authorization: bearer ZWQxMGYxNDgtZDQ0OC00MmUxLWE4ZTQtNWM2MGFkMzViZjI4Omd1aWQ=

If you have obtained a refresh_token and the access_token has expired (see expires_in in response), you can obtain a replacement access_token and a replacement refresh_token. All refresh requests are submitted to the REST API Authorize URL/Endpoint.

HTTP Header

To send the server your refresh_token, you must use the Authorization HTTP header.

The Authorization header is constructed as follows (after Base64 encoding):

• The refresh_token is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
• The token_type and a space, i.e. "bearer ", is then put before the encoded string.

For example, if the refresh_token is '2eb4848a-495e-4446-a421-b0b9603a52z9:guid' and the token_type is 'bearer', the header is formed as follows:

Authorization: bearer MmViNDg0OGEtNDk1ZS00NDQ2LWE0MjEtYjBiOTYwM2E1Mno5Omd1aWQ=

GET /authorize HTTP/1.1
Host: https://api.equipcalendar.com
Connection: keep-alive
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 Chrome/43.0.2357.124 Safari/537.36
Content-Type: application/json
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Authorization: bearer MmViNDg0OGEtNDk1ZS00NDQ2LWE0MjEtYjBiOTYwM2E1Mno5Omd1aWQ=

Response (Example)

Note: the response is the same as the original Basic (client_id & client_secret) response

Note: expires_in is returned in seconds

{
  "access_token": "8b72feec-304a-408b-81dc-0233d9f50944:guid",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "fe5e52b4-48b7-4f02-930c-e0a2c48cbf0e:guid"
}

Errors can and do occur. Along with a proper HTTP Status Code returned via the HTTP header, we also provide additional information in the JSON content.

General Example(s)

{
    "error": {
    "code": 400,
    "message": "Bad Request",
    "description": "Something bad happened.",
    "errors": null
    }
}

{
    "error": {
    "code": 401,
    "message": "Unauthorized",
    "description": "Invalid credentials.",
    "errors": null
    }
}

Revocation & Overuse

Both types of tokens, access_token and the refresh_token, can be revoked at any time. The most common reason is the generation of a new client_id and client_secret, which leads to an immediate revoke of all previous tokens associated with the previous client_id and client_secret.

Once a refresh_token has been utilized, and a new access_token generated, the refresh_token is considered used and it cannot be used again.

{
      "error": {
        "code": 400,
        "message": "Bad Request",
        "description": "Token revoked.",
        "errors": null
      }
}
                                            

{
      "error": {
        "code": 400,
        "message": "Bad Request",
        "description": "Token has already been refreshed.",
        "errors": null
      }
}
                                            

The Authorization header can be passed in a multitude of ways, but here are a few, simple examples.

Via the URL

Some browsers may support syntax for a username:password (i.e. client_id:client_secret) embedded within the URL for the basic authentication method as outlined in the URL specification.

Request (Example)

• client_id: 269a7997-8c8e-4041-a286-531ecee93ad1
• client_secret: 062f6075-2694-4844-b789-2121ea85b897

http://269a7997-8c8e-4041-a286-531ecee93ad1:062f6075-2694-4844-b789-2121ea85b897@api.equipcalendar.com

Response (Example)

Note: expires_in is returned in seconds

{
  "access_token": "ed10f148-d448-42e1-a8e4-5c60ad35bf28:guid",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "2eb4848a-495e-4446-a421-b0b9603a52z9:guid"
}

Via jQuery

The jQuery ajax() method supports a beforeSend function which can modify the XMLHTTPRequest object before it is sent.

Request (Example)

Note the use of the btoa() function to encode the client_id and client_secret strings using base64. The bota() methods has wide browser support.

function getAuth(client_id, client_secret){
    var encodedKey = window.btoa(client_id + ':' + client_secret); // encode a string
    $.ajax({
        cache: false,
	    url: encodeURI('https://api.equipcalendar.com/authorize'),
	    type: 'GET',
	    beforeSend: function (xhr) {
		    xhr.setRequestHeader('Authorization', 'Basic ' + encodedKey);
	    },
	    data: {},
	    contentType: 'application/x-www-form-urlencoded',
	    success: function () { },
	    error: function () { }
    });
}