Authentication¶

The Spry API uses OAuth 2.0 for secure authentication and authorization. This guide covers all authentication methods and security best practices.

Authentication Methods¶

Client Credentials Flow (Recommended)¶

The Client Credentials flow is ideal for server-to-server authentication where no user interaction is required.

Request¶

POST /apis/v2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=read write

Response¶

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write",
  "organisation_id": 74,
  "user_id": 276,
  "roles": [
      "ADMIN",
      "DOCTOR"
  ],
  "clinic_id_list": [
      44,
      58
  ],
  "name": "Sam Matthew"
}

Authorization Code Flow¶

Use this flow for applications that need to act on behalf of a user.

Step 1: Authorization Request¶

Redirect users to the authorization endpoint:

https://{base_url}/apis/v2/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=read write&
  state=RANDOM_STATE_STRING

Step 2: Exchange Code for Token¶

POST /apis/v2/oauth/token HTTP/1.1
Host: {base_url}
Content-Type: application/x-www-form-urlencoded

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

Scopes¶

Control access to resources with these scopes:

Scope	Description
`read`	Read access to all resources
`write`	Write access to all resources

Using Access Tokens¶

Include the access token in the Authorization header of your API requests:

GET /v2/patients HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Token Refresh¶

Access tokens expire after 1 hour. For long-running applications, implement token refresh:

Refresh Token Request¶

POST /apis/v1/oauth/token HTTP/1.1
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

Response¶

{
  "access_token": "new_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "new_refresh_token",
  "scope": "read write"
}