Authentication Guide

Basic HTTP authentication and OAuth 2.0 are both supported depending on the security requirements and technical limitations of the organization. Each of your applications is issued a workflow_token and workflow_secret (viewable in your dashboard) that are used in either method.

Make sure to not share your workflow_secret (never put it in repositories or leave human-readable in code) and always use HTTPS! OAuth 2 OR basic auth used for server-to-server communication are only as good as the security of the clients using our APIs. We want to make sure your information is as secure as possible!

Basic HTTP Authentication

To authorize per-request with HTTP basic auth, use this code:

curl -X POST https://sandbox.alloy.co/v1/evaluations \
     -H "Content-Type: application/json" \
     -u workflow_token:workflow_secret \
     -d $'{
       "name_first": "John",
       ...
     }'

If choosing to use HTTP basic auth, credentials must be passed for each request with the username being the workflow_token and the password as the workflow_secret. To implement HTTP basic auth yourself, the steps are as follows:

  1. Concatenate the application token and application secret together, separated by a colon
  2. Base64 encode the resulting string
  3. Pass the result in the authorization header, prefixed with the word “Basic” like Basic base64_encode(workflow_token:workflow_secret)

OAuth 2.0

To authorize once with OAuth 2.0, use this code:

curl -X POST https://sandbox.alloy.co/v1/oauth/bearer \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic ZHBERDZ6NG9sT1NJN040Zk1Dc0FsS2pGYTdyZUJZaHU6b0ptM25pUVgxUGR5NHo2NzVrZWZFSUtCZ0ZuOXRRNDU=" \
  -d '{
    "grant_type": "client_credentials"
  }'

If choosing to use OAuth, the application credentials must first be passed to a route in order to receive a bearer token. Each bearer token is valid for one hour. Alloy uses standard OAuth 2.0, so it is generally plug-and-play with most auth plugins or API clients. All you need to know is:

Grant Type: client_credentials Client ID: (workflow_token) Client Secret: (workflow_secret) Access Token URL: https://sandbox.alloy.co/v1/oauth/bearer

If you want to roll your own, just pass the application token and application secret via basic auth (as explained above) to POST /oauth/bearer with a grant type of “client_credentials”.

Alloy expects for the bearer token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <bearer_token>

Updated 11 months ago