Authentication Guide

OAuth 2.0

Many Lightcast APIs use the OAuth 2.0 Client Credentials flow for authentication. This guide explains how to request a token, how to use it, and how to manage token lifecycle best practices.

Most programming languages and frameworks provide built-in OAuth clients, but if yours does not, you can follow the examples below to implement the flow manually.

To get credentials, either speak with a sales representative or you can sign up for free to access the Skills and Titles APIs.

⚙️
You may request or reset credentials here:

Request credentials: https://lightcast.io/open-skills/access

Reset or retrieve credentials: https://lightcast.io/open-skills/access/reset

Once you have your client ID and client secret, you can follow the steps below or use our interactive reference page.

Get Token

To authenticate, you must request a Bearer token from the Lightcast Auth service. Tokens are valid for 1 hour and must be included with every authenticated API request.

Make a POST request to: https://auth.emsicloud.com/connect/token

Sample Request

{
  "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"
    }
  ]
}

Request Parameters

Parameter	Type	Description
`client_id`	string	The client ID provided by Lightcast.
`client_secret`	string	The client secret associated with your client ID.
`grant_type`	string	Must be set to `client_credentials.`
`scope`	string	One or more scopes that define API access (e.g., `"postings:us profiles:us"`). Space-delimited.

Sample Response

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Note that the Tokens expire after 3600 seconds. To maintain uninterrupted access, refresh the token before it expires.

Response Parameters

Parameter	Type	Description
access_token	string	The token used to authorize the API requests.
expires_in	integer	Number of seconds before the token expires.
token_type	string	Indicates the type of token. (Always Bearer).

Cache Token

You should cache the token for the duration of expires_in and avoid requesting a new token for every API call, as that may lead to rate limiting or unnecessary overhead.

Once the token expires, request a new one using the same flow.

Use Token

All authenticated Lightcast APIs require the token to be included in the HTTP Authorization header:

Authorization: Bearer <ACCESS_TOKEN>

Example

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

Lightcast Open

Lightcast Aegis supports creating new free users to allow usage of our Emsi_Open services. To do so, the querying client must have access to the client:manage scope (it is not required to call it specifically. It is innate). Ask Data Delivery for access if needed. When requesting your token, use scope=emsiauth.

An HttpStatusCode200 will be returned for any successful query.

Create a new client

View the example below:

{
	"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":[]
	}
}

ClientId will be generated by Lightcast Aegis.
If a conflicting email address is found, but the account does not have access to emsi_open, the user will be sent an email to confirm that they'd like to sign up for it.

An HTTPStatusCode409 will be returned if a conflicting email address is found that already has access to emsi_open.

Restrictions:

ClientName (string, alphanumeric and spaces + hyphens allowed)
Description (string, should be "Lightcast Open")
ContactName (string)
CompanyName (string, optional)
ContactEmail (string)

Change client email

This endpoint has been disabled temporarily.

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

An HTTPStatusCode409 will be returned if the clientid or secret are not found.

Retrieve clientid

Sends an email to the client noting their clientid.

{
	"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":[]
	}
}

An HTTPStatusCode409 will be returned if the posted email address is not found.

Reset client secret

Sends an email to the client confirming that they'd like to reset their secret.

{
	"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":[]
	}
}

An HTTPStatusCode409 will be returned if clientid or email is not found.