Authentication

How to authenticate with the Pool Office Manager API

Overview

The Pool Office Manager API uses OAuth 2.0 for authentication. All authentication operations are handled via REST endpoints. You need to obtain an access token and include it in the Authorization header of all API requests.

OAuth Flow

The authentication flow uses the OAuth 2.0 authorization code grant:

Call the authorize endpoint with user credentials
Receive an authorization code
Exchange the authorization code for access and refresh tokens

Authorize

Submit login credentials to receive an authorization code:

POST/m/authorize

Authenticate user and receive authorization code

curl -X POST "https://api.poolservicemanager.com/m/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "realm": "your-realm",
    "clientId": "your-client-id",
    "redirectUri": "https://your-app.com/callback",
    "state": "random-state-string"
  }'

Response:

{
  "code": "authorization_code_here",
  "state": "random-state-string"
}

Exchange Code for Token

Exchange the authorization code for access and refresh tokens:

POST/oauth/token

Exchange authorization code for access tokens

curl -X POST "https://api.poolservicemanager.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://your-app.com/callback",
    "client_id": "YOUR_CLIENT_ID"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Refresh Token

Use the refresh token to obtain a new access token when it expires:

POST/oauth/token

Refresh access token using refresh token

curl -X POST "https://api.poolservicemanager.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID"
  }'

Using the Token

Include the access token in the Authorization header with the Bearer prefix:

curl -X POST "https://api.poolservicemanager.com/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "query": "query { me { id email } }"
  }'

Validate Token

Check if the current access token is valid:

POST/oauth/validate

Validate current access token

curl -X POST "https://api.poolservicemanager.com/oauth/validate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns 200 OK if valid, or 401 Unauthorized if invalid.

Revoke Token

Revoke an access or refresh token:

POST/oauth/revoke

Revoke an access or refresh token

curl -X POST "https://api.poolservicemanager.com/oauth/revoke" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "TOKEN_TO_REVOKE"
  }'

Password Reset

Request and complete a password reset:

POST/m/request-password-reset-code

Request a password reset code

curl -X POST "https://api.poolservicemanager.com/m/request-password-reset-code" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "realm": "your-realm"
  }'

POST/m/reset-password

Reset password using the code

curl -X POST "https://api.poolservicemanager.com/m/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "RESET_CODE",
    "password": "new-password",
    "realm": "your-realm"
  }'

Error Responses

Authentication errors return specific error codes:

Status Code	Description
`400`	Bad Request - Invalid parameters or missing fields
`401`	Unauthorized - Invalid credentials or expired token
`403`	Forbidden - User lacks required permissions