Authentication overview

Cloud API authentication is based on bearer tokens.

• Public sign-in endpoints (no bearer token required):
  • POST /user-service/auth/sign_in
• Session/token endpoints (bearer token required):
  • PUT /user-service/auth/refresh_token
  • GET /user-service/auth/validate_token
  • DELETE /user-service/auth/sign_out

Use only production Cloud API URLs in public docs:

https://api.watergate.ai

Login

Authenticate with email and password to receive session details:

curl -X POST "https://api.watergate.ai/user-service/auth/sign_in" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@redacted.example",
    "password": "REDACTED"
  }'

Expected success response shape:

{
  "token_details": "REDACTED",
  "user_details": {}
}

Refresh

When your access token expires, refresh it with the current bearer token:

curl -X PUT "https://api.watergate.ai/user-service/auth/refresh_token" \
  -H "Authorization: Bearer REDACTED_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Expected success response shape:

{
  "token_details": "REDACTED",
  "user_details": {}
}

Logout / revoke

Invalidate the current server-side session token:

curl -X DELETE "https://api.watergate.ai/user-service/auth/sign_out" \
  -H "Authorization: Bearer REDACTED_ACCESS_TOKEN"

Typical success response:

{
  "success": true
}

Error handling

Common authentication/authorization errors:

• 401 Unauthorized — missing/invalid/expired credentials.
• 403 Forbidden — token is valid, but operation is not permitted for the caller.
• 422 Unprocessable Entity — request payload is syntactically valid JSON but fails API validation (for example, missing required fields).