API Authentication

Basic

Basic authentication is a very simple mechanism built-in to the HTTP protocol. It uses an authentication header made up of an easily-reversible encoded username and password combination. Basic authentication is not secure unless used with another mechanism such as SSL (HTTPS).

Token

This authentication scheme uses a token, sometimes also called an API key. Clients use the token when they communicate with the API. The key is usually stored in a query parameter or header and is considered a secret known only to the client and the server. As with Basic authentication, your API token should not be considered secure unless used with another mechanism such as SSL (HTTPS).

OAuth 2.0

OAuth 2.0 is an authorization framework that gives an API client limited access to an API on behalf of a resource owner (user). The API client may obtain access through a shared token or may initiate an interactive permission approval process for the resource owner.

Common OAuth 2.0 Grant Types

There are a few common grant types you may encounter when using OAuth 2.0.

• Authorization Code: A redirection-based flow where the client-side code (and thus client credentials) remain secret, e.g. behind a second web server.

• Implicit: A redirection-based flow where the client-side code (and thus client credentials) are not secret, e.g. an in-browser API client.

• Resource Owner Password Credentials: A resource owner (user) provides their username and password to the API client, which uses them to authenticate on behalf of the resource owner and obtain an access token.

• Client Credentials: A client can use its own credentials to access the API. Actions do not occur on behalf of any user, so the available functionality may be limited.

Common OAuth 2.0 URLs

There are a few common URLs you may encounter when using OAuth 2.0.

• Authorization URL: This is the URL a client redirects to when it needs to authorize a user. The user authenticates with the service and then approves the required permissions before being redirected back.

• Token URL: This is the URL a client requests to get a token that authenticates the client and authorizes certain actions on behalf of a resource owner. The token usually links the client, the resource owner, and allowed permissions. It may expire, at which point a refresh token may be used to obtain a new token.

OAuth 2.0 Scopes

Scopes provide granular permissions to resources. For example, an API client may have an article:write scope that allows it to create and edit articles, but because it is missing the article:delete scope it is not allowed to remove existing articles on behalf of the article owner.

OAuth 2.0 in Depth

For more information about OAuth 2.0, see here:

• An Introduction to OAuth 2.0
• OAuth 2.0 Specification & implementations