Skip to content

Authentication

Authentication with the API is handled via JSON Web Token (JWT) and HTTP Bearer headers. Generally, the authentication flow looks like the following:

Step 1: Get your Public and Private Keys

Locate your public and private keys in CEO, under Settings, Developer Access. Keep those secure, treat them like any password.

If you're using a service account, the keys are presented once when creating the account and will not be shown again.

Step 2: Prepare your JWT

Set your public key as a JWT claim called pk and sign your request with your private key. Your private key should not be sent as part of your JWT.

Step 3: Use your JWT

Use the JWT as a bearer token to access the rest of the API:

Request: 

GET /v3/assignments HTTP/1.1
Content-Type: application/json
Authorization: Bearer XXXXXXXX

Step 4: Keep an eye on your JWT

If your JWT is invalidated, the server will respond with a "Forbidden" error, which you should handle by refreshing your JWT:

Request: 

GET /v3/assignments HTTP/1.1
Content-Type: application/json
Authorization: Bearer XXXXXXXX

Response: 

HTTP/1.1 403 Forbidden
Content-Type: application/json
Connection: close

Request: 

GET /v3/token/refresh HTTP/1.1
Content-Type: application/json
Authorization: Bearer XXXXXXXX

Response: 

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close

{
    "token": "XXXXXX..."
}

Errors

For valid requests, the system will always respond with a 200 OK status. For anything else, you'll get an error code and a message. The system will respond with standard HTTP errors in the 4XX and 5XX range for a number of actions. Some of the common errors and what they mean are:

  • 400 Bad Request - Your request was technically ok, but was missing something. Check the message response.
  • 401 Unauthorized - You don't have access via your ACL.
  • 403 Forbidden - Your token has expired.
  • 404 Not Found - The item you were trying to access is gone.
  • 413 Request Entity Too Large - Your file or content item was too large (this shouldn't really happen).
  • 415 Unsupported Media Type - That one is pretty clear.
  • 417 Expectation Failed - This one is basically the server saying "idunno". Check the message content.
  • 500 Internal Server Error - Something wazzed out. Check the message content and contact support.
  • 501 Not Implemented - The thing you're trying to do may not be fully implemented.
  • 503 Service Unavailable - Server freaked out and couldn't respond.

Versioning

The version identifier is required for ALL API requests. The current version is v3. API versioning will follow standard Semantic Versioning and SNworks will inform users of breaking changes and version retirement well ahead of implementation.