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.

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:

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

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.address@xen.com\"}",
		"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.address@xen.com\"}",
		"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\": \"test-email@agnitio.emsicloud.com\"}",
		"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.

200200

400400