Skip to content

Set up user authentication

Project X API Gateway authenticates users by API keys/tokens sent along with each request. When a user activates a new subscription by paying the first invoice, Project X issues a unique API key and the customer can get it from the subscription page in the self-service portal.

For the gateway to know where to find the API key in the HTTP request, a token extraction strategy needs to be configured. The strategy consists of one or more steps.

In order to configure token extraction strategy, navigate to APIs → choose an API → API Settings → Authentication tab.

Warning

If you make changes to the user authentication settings, make sure to update the authentication instructions displayed to your customers in the self-service portal and on the checkout page.

Default strategy

By default, the gateway looks for the API key in the X-Billing-Token request header.

The header name is chosen to avoid interference with "Authorization" header in cases when the API uses it for internal authentication.

API key in "Authorization" header

If you'd like to use Authorization: Bearer <token> scheme, configure the token extraction strategy as follows:

  1. Click "Delete step" in order to clear the step list.

  2. Click "Get request header value".

  3. Enter Authorization as header name.

  4. Click "Split it by delimiter".

  5. Enter " " (space) as delimiter.

  6. Click "Take value by path or apply expression".

  7. Enter input[1] as expression.

    Note

    In the expression you can use the result of a previous step, it's stored in a variable named input.

  8. Click "Save".

Now the gateway will look for the token in Authorization: Bearer <token> header.

In fact, the scheme could be anything, not necessarily Bearer.

Other valid examples are

  • Authorization: Basic <token>
  • Authorization: Digest <token>
  • etc.

API key in an arbitrary header

If you'd like to use a custom header for the access token (e.g. X-My-Api-Token: <token>), configure the token extraction strategy as follows:

  1. Click "Delete step" in order to clear the step list.

  2. Click "Get request header value".

  3. Enter X-My-Api-Token as header name.

  4. Click "Save".

Now API users can send the token in X-My-Api-Token: <token> header.

API key in JSON body

Let's say the request body is a JSON object containing access token:

{
    "auth": {
        "token": "<API key>"
    },
    "payload": {
        // ... actual request payload
    },
}

Project X API Gateway needs to parse the request body as JSON and take the API key from that JSON object by the specified path.

In order to implement that, configure the token extraction strategy as follows:

  1. Click "Delete step" in order to clear the step list.

  2. Click "Get request body".

  3. Click "Decode it as...".

  4. Choose JSON from the dropdown list.

  5. Click "Take value by path or apply expression".

  6. Enter input.auth.token as expression.

    Note

    In the expression you can use the result of the previous step, it's stored in a variable named input.

  7. Click "Save".

The gateway will decode the request body as JSON and extract the token value by the specified path.