Skip to content

API Reference

Test authentication

client.auth.test(, ?): AuthTestResponse { auth_method, authenticated, company_id, 6 more }

GET/auth/test

Simple endpoint to test if authentication credentials are valid. Returns authentication status, company/user info, and the scopes granted to the token. Useful for debugging during development.

ParametersExpand Collapse

params: AuthTestParams { rotorAPIVersion }

rotorAPIVersion: "1.1.0"

Required OpenAPI version header.

ReturnsExpand Collapse

AuthTestResponse { auth_method, authenticated, company_id, 6 more }

auth_method?: "api_key" | "unknown"

One of the following:

"api_key"

"unknown"

authenticated?: boolean

company_id?: string

message?: string

rotor_api_version?: string

scopes?: Array<string>

Scopes granted to this token

status?: string

timestamp?: string

user_id?: string | null

Null for API key authentication

formatuuid

Test authentication

import Rotor from 'getrotor';

const client = new Rotor({
  rotorAPIVersion: '1.1.0',
  apiKey: process.env['ROTOR_API_KEY'], // This is the default and can be omitted
});

const response = await client.auth.test({ 'rotor-api-version': '1.1.0' });

console.log(response.company_id);

{
  "status": "success",
  "message": "Authentication successful",
  "authenticated": true,
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": null,
  "auth_method": "api_key",
  "scopes": [
    "leads:read",
    "customers:read"
  ],
  "timestamp": "2026-01-15T14:30:00Z"
}

{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}

{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

Returns Examples

{
  "status": "success",
  "message": "Authentication successful",
  "authenticated": true,
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": null,
  "auth_method": "api_key",
  "scopes": [
    "leads:read",
    "customers:read"
  ],
  "timestamp": "2026-01-15T14:30:00Z"
}

{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}

{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}