API authentication and authorization |

How to document with authentication

Edit me

This part gleaned tips around articulating conceptual topics for an API product out of Tom’s API documentation tutorial.

Authentication vs authorization

Authentication: Verify a user account
Authorization: Verify user privilege

Different types of authorization

API keys
Basic Auth
HMAC
oAuth

Basic Auth

The sender stores a username: password into the request header. The username and password are encoded with Base64 to ensure safe tranmission, for example:

Authorization: Basic bG9sOnNlY3VyZQ==

API calls based on Basic Auth comform to HTTPS.

HMAC (Hash-based message authorization code)

A stronger type of authentication, more common in financial APIs. A key only known only to the sender and the receiver underscores its security…

oAuth Work Flow

One-legged OAuth: Applies when you don’t have sensitive data to secure
Three-legged OAuth: Consists of three roles
- Authentication Server
- Resource server (API server)
- The user or app

Video Tutorial: OAuth explained plainly

What to document with authentication

Do not go into specifics as to the internal details of your authentication process. Expect to need to explain some necessary information:

How to get API keys
How to authenticate requests
Error messages related to invalid authentication
Sensitivity around authentication information
Token expiration times

Note: If you have public and private keys, you should see to it the private keys shall not be shared for the sake of security. When privileges are assigned at different layers, also include such information prominently.

Samples

SendGrid

API Keys
- Types of API keys: Full Access / Restricted Access / Billing Access
  - API key permissions: No Access / Read Access / Full Access
- Managing API keys
  - Creating an API key
- Editinig an API key
- Deleting an API key
- Replacing an old API key with a new one
- Testing an API key

Twitter

Authentication
- Authorizing a request
- Collecting parameters: Consumer key / Nonce (token ID generated by the application for each request) / Signature / Signature method / Timestamp / Token / Version
- Building the header string

Amazon Web Services

HMAC-SHA256 Signatures for REST request
- Authentication Parameters
  - Signature - Required
  - Timestamp - Required
- Basic Authentication Process