Client Authentication

Orbital uses authentication provided by SecureX and Secure Endpoint instead of maintaining another set of logins and users. Customers must create a set of client credentials for their applications to use Orbital.

Note: A given set of credentials will only work in one region – you cannot use North American credentials in Europe, for example.

Creating a New Client

Creating API credentials is now done through SecureX. Refer to the API Clients topic of the SecureX online documentation for information on Creating API Client Credentials. To access this topic, follow the path: SecureX Help -> Administration -> API Clients.

Getting an Access Token

Your client credentials are used for exactly one API in Orbital, getting an access token that you can use for other APIs. This token naturally expires after a brief period of time, so your application must get it a new one periodically.

The following request exchanges your client ID and password for a token:

http --auth $client:$secret \
     POST https://$service/v0/oauth2/token

The response will be a JSON object, containing a token and expiry

{
    // Expiry is an ISO 8601 date and time, after which, the token will no longer be accepted by Orbital.
    "expiry": "2020-03-03T15:42:50.783024-08:00"

    // Token is an access token that can be used to authenticate for Orbital APIs.
    "token": "eyJtZXNzYWdlIjogIllvdSBkaWRuJ3QgdGhpbmsgd2Ugd291bGQgZ2l2ZSB5b3UgdGhpcywgZGlkIHlvdT8i"
}

We will assume the value in token is in your environment as $token for our examples. You can do this in Bash using JQ and HTTPie with:

token=$(http --auth $client:$secret \
     POST https://$service/v0/oauth2/token |
jq -r .token)

Checking Your Token

Orbital has a simple API, GET /v0/ok that can be used to confirm that your token will work.

http https://$service/v0/ok \
     "Authorization: Bearer $token"

If successful, you will see the following, with HTTP status 200:

HTTP/1.1 200 OK

{
    // login information reflects the user that created the client.
    "login": {
        "email": "joe.maldive@threatgrid.com",
        "organization": "149f631c-4b50-478b-ae16-f86fabda0d31",
        "user": "9b16e8ca-1b43-42c0-9fb9-3f6d2cd8aa8d",
        "userName": "Joe Maldive"
    },
    "message": "OK"
}

When a token has expired or incorrect, you will see:

HTTP/1.1 403 Unauthorized

{
    "error": "authentication invalid"
}

If your token is missing, you will see:

HTTP/1.1 401 Unauthorized

{
    "error": "authentication required"
}

Orbital can provide help if you think this is in error – the X-Orbital-Request-Id header in Orbital’s responses can be looked up, and we can provide more details. This is generally true for any request in Orbital, although it is only authentication where our errors should be terse.

Return to Table of Contents