Client Authentication

Many services at Authentise require some form of client authentication. That is, the request being made must be proven to be authentic. There are generally two ways of doing so: via API token and via a user session. If you are a partner of Authentise you’ll use the API token method as outlined in design-streaming-api. All other users will use the user session authentication outlined below.

Please note that when you create a user using the instructions below you automatically agree to Authentise’s Terms of Service.

Creating a User

To create an authenticated session you’ll first need a user account. You can create one via the Users service. The request looks like this:

POST https://users.authentise.com/users/
Content-Type: application/json

{
    "email"     : "eli @uthentise.com",
    "name"      : "Eli Ribble",
    "password"  : "my-secret",
    "username"  : "EliRibble",
}

This request creates a new user for me. I’ve obfuscated my email just a bit in this example to make it a bit harder for bots to spam me. The response should be a 201 indicating success and a Location header will be provided in the response that lets me know where I can GET information about my user.

Creating a Session

Now that I have a user I can create a new session with Authentise.

POST https://users.authentise.com/sessions/
Content-Type: application/json

{
    "username"  : "EliRibble",
    "password"  : "my-secret",
}

This will return a 201 again on success and provide a Cookie called session. The cookie will have the domain set to anything within the authentise.com domain so that the session is included with requests to any of the other services.

You’ll need to include this cookie in any of the requests you make to Authentise’s services. If you fail to do so, or you provide an expired cookie, you’ll receive a 401 response code indicating your request was unauthorized.

If you make too many requests using a given session you may also receive a 429 status code which indicates you’ve hit our rate limiting and you need to stop sending so many requests.