A step towards better Web API authentication

Staff Software Engineer

November 08, 2016

Note: This blog was updated on February 13, 2017 to reflect changes to our token scope names. On May 15, 2017, we are replacing the account API Key with Personal API Tokens, offering greater security and control over our API. For more details check out our API documentation.

The following blog is based on a talk Toru gave at Altitude, our customer summit. Read the recap of the event here.

The Fastly API is an integral part of our CDN, as one of our main objectives is to provide a great developer experience — using our APIs, customers are able to instantly reflect configuration changes, purge content, and perform anything that is available on the Fastly control panel from their application. A natural concern with such powerful convenience is security, such as leaked credentials or a compromised, over-privileged API client. Hence, a flexible, scalable, and secure authentication and authorization mechanism is crucial for developers to confidently embrace a Web API. In this blog post, I’ll cover API tokens, our new API authentication method.

Improved Fastly API authentication

Customer feedback told us that our existing API authentication methods (API key and session cookie) could benefit from some updates. For the first iteration of improvements, we decided to tackle the following limitations:

Possible downtime caused by API key rotation
Only one API key is provided per customer organization
API key cannot represent the requesting user’s capabilities
Lack of support for two-factor authentication

Introducing API Tokens

What came out of this iteration was API token-based authentication. API token introduces a user-level access token that enables our API to identify who the request is made on behalf of and that person’s capabilities. We’re also excited to provide more flexibility by allowing individual users to create multiple tokens to better manage the API access from their projects. For extra safety, tokens can be given a limited scope of capabilities and finite lifespan. Token creation and revocation are also audit logged to help better secure your services through monitoring.

To help users switch, tokens by default are currently scoped with a global scope which, as the name suggests, grants a token with equivalent access level as an API key. In other words, an API token with global scope can be considered a drop-in replacement for an API key.

In summary, API Tokens immediately provide the following benefits:

API Tokens are associated to a user
Users can create multiple tokens
Supports two-factor authentication for enhanced security
Role-based access control is now enforceable
Options to limit token scope and set expiration for extra safety
Audit logged for visibility into new and revoked tokens

Quick tutorial

To begin authenticating with a token, you must first create one. Here’s an example curl command that will create a purge-only token on success.

curl -H "Fastly-OTP: 123456" \
           -d "username=me@foo.bar&password=$SECRET" \
           -d "name=my_first_token" \
           -d "scope=purge_select" \
           https://api.fastly.com/tokens

On success, the above request will respond with a result that resembles the following structure:

{
    "id": "5YvQH3Rg4bPPkhvPC6WFm2",
   "user_id": "1dZ0KVnlsFXc3ZiW9hsAb3",
   "access_token": "d3cafb4dde4dbeef",
   "service_id": null,
   "name": "my_first_token",
   "scope": "purge_select",
   "created_at": "2016-10-18T23:04:20+00:00"
}

Congratulations — you now have a token that can only be used to make URL or surrogate key purge requests on your behalf.

From here on, you’ll include the access_token value in the Fastly-Key HTTP header to make authenticated requests. For example, here’s how to make a surrogate-key based purge request using our new token:

curl -H "Fastly-Key: d3cafb4dde4dbeef" \
           https://api.fastly.com/service/xyz/purge/my_surrogate_key

Those who are familiar with our API might notice that this is also how you would send an authenticated request using an API key. Take a look at our documentation for more detailed and up-to-date information on API Tokens.

An improved Web API authentication and authorization mechanism enables developers to confidently implement creative and productivity-boosting software, while minimizing the risk of API-related incidents. Our new token-based authentication is a step towards this ideal developer platform experience – we look forward to your feedback.

Watch the video of Toru’s talk below, and stay tuned for more talks from Fastly Altitude.