How to Describe Authentication in API Blueprint?

It is possible to describe your API authentication within API Blueprint.

Describing Basic Auth in API Blueprint

The easiest Authentication framework is Basic access authentication. The only step needed is to specify an Authorization header in your request, like this:

FORMAT: 1A

# Basic Auth API

## Basic Auth protected resource [/protected]

### Status [GET]
+ Response 401
    + Headers

            WWW-Authenticate: Basic realm="protected"

+ Request
    + Headers

            Authorization: Basic ABC123

+ Response 200 (application/json)

            {
                "status": "ok"
            }

You can also specify a 401 response with a WWW-Authenticate header for an unauthorized or failed requests, which will force the client to provide credentials.

Describing OAuth 2 Bearer schema in API Blueprint

OAuth 2 also relies on exchanging headers and payloads, which can be described in API Blueprint. Take a look at the following example, showcasing:

  • Exchanging grant for an OAuth 2 Bearer token
  • Using this Bearer token to access a protected resource
  • Using MSON for describing data structures
FORMAT: 1A

# OAuth 2
This API Blueprint showcases OAuth 2.

## OAuth token exchange [/oauth/token]
Exchange credentials for `access_token`. Supported types:

+ `client_credentials`
+ [`urn:ietf:params:oauth:grant-type:jwt-bearer`](https://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-03#section-6)

### Exchange credentials for token [POST]
+ Request
    + Attributes (OAuth grant request)
    + Headers

            Authorization: Basic ABCDEF

+ Response 200 (application/json)
    + Attributes (OAuth valid response)

+ Request
    + Attributes (OAuth jwt-bearer grant request)

+ Response 200 (application/json)
    + Attributes (OAuth valid response)

## OAuth 2 Bearer Token protected resource [/protected]
### Status [GET]
+ Request
    + Headers

            Authentication: Bearer JWT

+ Response 200 (application/json)
    + Attributes (Server response)

# Data Structures
## OAuth grant request (object)
+ `grant_type`: `client_credentials` (string, required)

## OAuth jwt-bearer grant request (object)
+ `grant_type`: `urn:ietf:params:oauth:grant-type:jwt-bearer` (string, required)
+ assertion: `eyJhbGciOiJIUzI1NiJ9.e30.XmNK3GpH3Ys_7wsYBfq4C3M6goz71I7dTgUkuIa5lyQ` (string, required)

## OAuth valid response (object)
+ `access_token`: `eyJhbGciOiJIUzI1NiJ9.e30.XmNK3GpH3Ys_7wsYBfq4C3M6goz71I7dTgUkuIa5lyQ` (string, required) - valid JWT
+ scope: all (string, required) - scopes of current token
+ `expires_in`: 300 (number, required)
+ `token_type`: Bearer (string, required)

## Server response (object)
+ status: ok (string, required)

Authentication in Dredd tests

If you need to desribe Authentication for your Dredd tests, you can use Dredd hooks to prepare your requests. For example generate valid request credentials for resources in your test environment.

Future development

Currently there is an RFC for Authentication framework in API Blueprint that will simplify describing Authetication in API Blueprint.

This should allow you to describe Authentication schemes like:

Related topics