Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.readingsteps.uk/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
ScopeDescription
readRead access to user data
writeWrite access to user data
adminAdministrative access (requires approval)

​
Error Handling

​
Common Errors

Error CodeDescription
invalid_requestThe request is missing a required parameter
invalid_clientClient authentication failed
invalid_grantThe provided authorization code is invalid
invalid_scopeThe 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