OAuth 2.0

Requests to several Lightcast APIs are authenticated with the standard OAuth2 client-credentials flow using JSON Web Tokens. Your programming language and/or framework of choice probably has a library or middleware component that you can drop in to implement this scheme. This is our recommended approach, but in the event that your language doesn't make this easy we will detail how to implement the flow yourself.

To get credentials either speak with a sales representative or sign up for free! Our free tier allows access to our Lightcast Skills and Titles APIs. You can apply to get your own credentials here.
Note: If you need to reset or retrieve your credentials that can be done here.

Once you get your id and secret you can either use the below or use our interactive reference page.

Get a token

The first step in the client credentials flow to fetch a token. You can then use this token to make subsequent authenticated requests to the API you're using. To fetch a token, you need to make a POST request to https://auth.emsicloud.com/connect/token with a few form parameters:

Code Examples

{
  "url": "https://auth.emsicloud.com/connect/token",
  "method": "POST",
  "postData": {
    "mimeType": "application/x-www-form-urlencoded",
    "params": [
      {
        "name": "client_id",
        "value": "YOUR_CLIENT_ID"
      }, {
        "name": "client_secret",
        "value": "YOUR_CLIENT_SECRET"
      }, {
        "name": "grant_type",
        "value": "client_credentials"
      }, {
        "name": "scope",
        "value": "YOUR_SCOPE"
      }
    ]
  },
  "headers": [
        {
          "name": "content-type",
          "value": "application/x-www-form-urlencoded"
        }
      ]
}

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkQ4NzM3ODcyNDdFRDFEQ0QxQTU5MkE4RDY4QUM0MUE5Q0U3MEZEQjYiLCJ0eXAiOiJKV1QifQ.eyJuYmYiOjE1MzQ4ODgxODMsImV4cCI6MTUzNDg5MTc4MywiaXNzIjoiaHR0cDovL2F1dGguZW1zaWNsb3VkLmNvbSIsImF1ZCI6Imh0dHA6Ly9hdXRoLmVtc2ljbG91ZC5jb20vcmVzb3VyY2VzIiwiY2xpZW50X2lkIjoibWV0YWRvY3MiLCJzY29wZSI6WyJkYXRhc2V0OmVtc2kuKjoqOioiLCJlbXNpYXV0aCJdfQ.QbML016MNQ7w6MwgoRU_KwvPhbloyKd7sDoQIgFbcquCuuQ060iXoRbn_V9vxPZxseATZCQW5mhddmvXps4CmlydyCl0CKeKAytMvLkXVSnU_ld232ufhvtg7Kd8A0sK4ntmZuIMAaNNumRnVV9Uz8Fj9XZYsdmpddPFaH79_wl4xrO1etvT1wXM6iRmAWkiA81XERvP2LIDuB-WH1B2gIqW1hICJgjifJ3VM-90COS3pJK-fEtn6ijSZlmw-eogFnPmN1I41lyGJKbZe41eWlds7CDEgrisXyKHp-pJ6557c02CAMlGEVntuRsE2pfqyKD-_xoHecL2WKxm3wIx_w",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Cache your token

The response to your token request will contain an access_token, which is an encoded JSON Web Token (see http://jwt.io for reference). We recommend caching this token and not fetching a new one before every API request. You may cache the token for the duration indicated by the expires_in response field (returned in seconds). After the number of seconds indicated by the expires_in response field have elapsed, the access_token will no longer be valid and you'll need to repeat the process.

Use your token

Lightcast APIs that require OAuth 2.0 authentication accept their token in an authorization header of this format: authorization: Bearer <ACCESS_TOKEN>

Code Examples

{
  "method":"GET",
  "url":"https://example.com",
  "headers": [
    { "name":"Authorization", "value":"Bearer <ACCESS_TOKEN>" }
  ]
}

{
	"method": "POST",
	"url": "https://auth.emsicloud.com/client/createfree",
	"headers": [
    { "name":"Authorization", "value":"Bearer <ACCESS_TOKEN>" }
	],
	"postData": {
		"mimeType": "application/json",
		"text" : "{ \"ClientName\": \"Gordon Freeman\", \"Description\": \"Rise and shine\", \"ContactName\": \"Gordon Freeman\", \"CompanyName\": \"Black Mesa\", \"ContactEmail\": \"[email protected]\"}",
		"params":[]
	}
}

{
	"method": "POST",
	"url": "https://auth.emsicloud.com/client/forgot/clientid",
	"headers": [
    { "name":"Authorization", "value":"Bearer <ACCESS_TOKEN>" }
	],
	"postData": {
		"mimeType": "application/json",
		"text" : "{ \"Email\": \"[email protected]\"}",
		"params":[]
	}
}

{
	"method": "POST",
	"url": "https://auth.emsicloud.com/client/forgot/secret",
	"headers": [
    { "name":"Authorization", "value":"Bearer <ACCESS_TOKEN>" }
	],
	"postData": {
		"mimeType": "application/json",
		"text" : "{ \"ClientId\": \"freeuser1\"}",
		"params":[]
	}
}