API Authentication

How to authenticate requests to the Live Editor API using OAuth 2.0.

Based on the OAuth 2.0 spec

Authentication and authorization through the Live Editor API implements parts of the OAuth 2.0 specification.

There are 2 parts to gaining access to the API through OAuth:

1. Authentication: submit a request to the /oauth/token endpoint to gain an access_token.
2. Authorization: access the other API endpoints using the newly-obtained access_token in an Authorize HTTP header.

And a bonus 3rd step for when the access_token expires:

3. Refresh Token: submit a request to the /oauth/token endpoint with the refresh_token from step 1 in order to gain a new access_token.

More details about each step follow in this article.

Authentication

You may authenticate clients through the Resource Owner Password Credentials flow or the Authorization Code Grant flow.

Resource Owner Password Credentials flow

This grant type specifies that the client sends a set of credentials to the API server (username and password) in exchange for an access_token.

This is recommended for developing in-browser JavaScript-based clients that will communicate with the Live Editor API.

Example request:

      POST /oauth/token.json HTTP/1.1
      Host: coffee.api.liveeditorapp.com
      Content-Type: application/x-www-form-urlencoded
      
      grant_type=password&username=john.smith@example.com&password=B00t54r3c00l

If those credentials are valid, the Live Editor API will return a set of authorization tokens:

      HTTP/1.1 200 OK
      Content-Type: application/json;charset=UTF-8
      Cache-Control: no-store
      Pragma: no-cache
      
      {
        "token_type": "bearer",
        "access_token": "3ec78864cc017982fdeeb0c092bfbea3f104df1e18c9c67f222581d9353f3fce",
        "refresh_token": "cb03c07b8845ea7b40251b0df46839177bd7b51b3dd1d23f167890b9e1549f07",
        "expires_in": 7060
      }

Authorization Code Grant flow

This grant type requires the client to authenticate with a client_id and client_secret.

This is recommended for developing server-side and desktop clients that will communicate with the Live Editor API.

There are 2 steps to using the Authorization Code Grant flow.

1. Generate client_id and client_secret

Coming soon…

2. Authenticate with the client_id and client_secret

Example request:

      POST /oauth/token HTTP/1.1
      Host: coffee.api.liveeditorapp.com
      Content-Type: application/x-www-form-urlencoded
      
      grant_type=authorization_code&client_id=THE_ID&client_secret=THE_SECRET&redirect_uri=urn:ietf:wg:oauth:2.0:oob

If those credentials are valid, the Live Editor API will return a set of authorization tokens:

      HTTP/1.1 200 OK
      Content-Type: application/json;charset=UTF-8
      Cache-Control: no-store
      Pragma: no-cache
      
      {
        "token_type": "bearer",
        "access_token": "3ec78864cc017982fdeeb0c092bfbea3f104df1e18c9c67f222581d9353f3fce",
        "refresh_token": "cb03c07b8845ea7b40251b0df46839177bd7b51b3dd1d23f167890b9e1549f07",
        "expires_in": 7060
      }

Authorizing requests

The Live Editor API requires clients to authorize requests through the use of Bearer Tokens.

To gain access to an access_token, use one of the methods described above in the Authentication section.

Once your client has obtained an access_token, it must include it as a Authorization HTTP header Bearer token in all subsequent requests to the API.

Example HTTP header:

      Authorization: Bearer 3ec78864cc017982fdeeb0c092bfbea3f104df1e18c9c67f222581d9353f3fce
      

Refresh tokens

The Live Edit API supports OAuth 2.0 Refresh Tokens.

To refresh access to the API after the access_token has expired, submit a grant_type=refresh_token request to /oauth/token.

      POST /oauth/token HTTP/1.1
      Host: coffee.api.liveeditorapp.com
      Content-Type: application/x-www-form-urlencoded
      
      grant_type=refresh_token&refresh_token=cb03c07b8845ea7b40251b0df46839177bd7b51b3dd1d23f167890b9e1549f07

The API will respond with a new access_token and refresh_token after your client provides a valid refresh_token.