This guest post comes from Peter Gruenbaum, founder of SDK Bridge, a company that writes API documentation so that your developers don’t have to. He has worked as an API writer to describe APIs for eCommerce, traffic prediction, electric utilities, mobile phones, and tractors, just to name a few.
OAuth is becoming a very popular way to control authorized access to Web APIs and the data that they return. Although it's one of the most straightforward ways to accomplish this, it's still rather confusing to use. If your API uses OAuth, then you need to be able to describe it so that developers can quickly understand what they need to do.
OAuth can be a very complex topic, and not all developers are familiar with it. It's not effective to just point developers to the relevant OAuth specification and expect them to understand it. However, your documentation doesn't need to explain all the inner workings of OAuth either. This article explains the important pieces that your documentation should cover so that your developers can get the authorization they need to use your API.
First, it's important to mention which version of OAuth you are using. Currently, versions 1.0, 1.0 revision A, and 2.0 are available. Most new APIs use version 2.0, but there are some older APIs (Twitter, Dropbox, and parts of Google) that use version 1.0. The version number is important because the flow of tokens is different for the different versions. This article focuses on what is used for OAuth 2.0.
For OAuth2.0, there are four types of grant types, which represent different types of credentials that can be used to access your protected resources. The four grant types are: authorization code, implicit, resource owner password credentials, and client credentials. Be sure to mention which type of grant type you are using, and how to specify it. It should be passed in as a parameter with one of these values:
OAuth works by having an application communicate with two servers: the authorization server and the resource server. The section describes what should be included in how to make requests to the authorization server.
Document the URL for the authorization server, and describe the parameters that are required for authorization. Some important parameters include:
client_id — Identifies which client is making the request. This is often the application key that the developer received when registering the application.
redirect_uri — An optional parameter that redirects back to a client's URL. If you are using this, be sure to explain how the redirection will work and suggest how developers might handle the redirection. Note that the redirect URI may be required to be registered beforehand; if so, you need to explain how to perform the registration.
scope — An optional parameter that limits the API access. If you are using this, be sure to include a table where each row contains a value for this parameter, as well as which API calls are accessible for that value. For example, one scope might provide full access, whereas another might only include read-only access.
grant_type — A parameter that specifies the grant type. See the Grant Type section above.
response_type — A parameter that specifies the response type, which can be either
token. If set to
code, the response will include an OAuth code which can be exchanged for an access token as per the server-side authentication flow. If set to
token, the response will include an OAuth user access token in the fragment of the URL the user is redirected to, as per the client-side authentication flow.
Describe the response that is returned. There are two kinds of responses you need to explain. The first is the response from the original request. For example, this might be HTML that should be embedded into a webpage that allows a user to log in. For the second, if you are using a redirect_uri, then you need to describe what parameters are added to that URL. If authorization codes or access tokens are returned, point out how the developer can find them.
Access tokens can expire, and so the OAuth authorization server can also return refresh tokens in additional to access tokens. Explain how refreshing works by describing:
- How long an access token is valid for
- Where to find the refresh token in the response
- How to use the refresh token to obtain a new access token
Once they have an access token, developers can use it to call the OAuth resource server, allowing them access to your API. When describing how to use the token, include how the token is passed to the API server. Often the token is included in the Authorization header, and needs to be either
authorization: basic or
Showing how codes and tokens flow between the application, the authorization server, and the resource server can be accomplished nicely with diagrams. Examples of simple, clear diagrams can be found in the documentation from Google called Using OAuth 2.0 to Access Google APIs. It provides information on how to use OAuth for a variety of scenarios that call Google APIs, including web server applications, installed applications, and devices with limited input capability.
Provide a Walk-through
It can be extremely useful to provide a walk-through for your developers. Show them sample requests to and responses from the authentication server, including using refresh tokens. Then show them how they would take an access token and make an API call. Of course, make sure that you are not using actual working credentials or keys.
In conclusion, if your API uses OAuth, you need to explain how developers can gain access to your APIs with enough information that they can get up and running, but without explaining all of the complexity of OAuth. You should cover:
- Version and authorization grant type
- How to call the authentication server
- How to specify scope in order to limit API access
- How to refresh tokens
- How to call the resource server
- Simple diagrams as to how data flows
- A walk-through that illustrates a simple task using OAuth