Authentication

The ReadingSteps API uses OAuth 2.0 for authentication. All API requests require a valid access token.

Getting Started

1. Create an API Key

Visit the Developer Portal to create your API key.

2. Choose Your Authentication Method

We support two authentication methods:

OAuth 2.0 Authorization Code Flow (recommended for web apps)
API Key (recommended for server-to-server applications)

OAuth 2.0 Authorization Code Flow

Step 1: Redirect to Authorization URL

https://auth.readingsteps.uk/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read+write&
  state=RANDOM_STRING

Step 2: Exchange Code for Access Token

POST https://auth.readingsteps.uk/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read write"
}

API Key Authentication

For server-to-server applications, use your API key in the request header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.readingsteps.uk/v1/users/me

Token Refresh

Access tokens expire after 1 hour. Use your refresh token to get a new one:

POST https://auth.readingsteps.uk/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Scopes

Available OAuth scopes:

Scope	Description
`read`	Read access to user data
`write`	Write access to user data
`admin`	Administrative access (requires approval)

Error Handling

Common Errors

Error Code	Description
`invalid_request`	The request is missing a required parameter
`invalid_client`	Client authentication failed
`invalid_grant`	The provided authorization code is invalid
`invalid_scope`	The requested scope is invalid

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired"
}

Best Practices

Store tokens securely (never in client-side code)
Use HTTPS for all API calls
Implement token refresh logic
Revoke unused tokens
Monitor token usage for suspicious activity

​Authentication

​Getting Started

​1. Create an API Key

​2. Choose Your Authentication Method

​OAuth 2.0 Authorization Code Flow

​Step 1: Redirect to Authorization URL

​Step 2: Exchange Code for Access Token

​Response

​API Key Authentication

​Token Refresh

​Scopes

​Error Handling

​Common Errors

​Example Error Response

​Best Practices