API reference

Technical API specification for the Automator OAuth 2.0 implementation following the Client Credentials Grant flow as defined in RFC 6749 Section 4.4.

Table of contents

• Authentication flow
• Endpoints
  • POST /oauth/token

Authentication flow

┌─────────────┐                                ┌─────────────┐
│             │                                │             │
│   Client    │                                │  Automator  │
│             │                                │             │
└──────┬──────┘                                └──────┬──────┘
       │                                              │
       │  POST /oauth/token                           │
       │  ─────────────────────────────────────────>  │
       │  grant_type=client_credentials               │
       │  client_id=svc_...                           │
       │  client_secret=...                           │
       │  service_uuid=...                            │
       │  profile=...                                 │
       │  environment=...                             │
       │                                              │
       │                                              │
       │  200 OK                                      │
       │  <─────────────────────────────────────────  │
       │  {                                           │
       │    "access_token": "eyJhbG...",              │
       │    "token_type": "Bearer",                   │
       │    "expires_in": 3600,                       │
       │    "scope": "service:call"                   │
       │  }                                           │
       │                                              │
       │                                              │
       │  POST /service/{profile}/{env}/json/{uuid}   │
       │  ─────────────────────────────────────────>  │
       │  Authorization: Bearer eyJhbG...             │
       │  {"data": "value"}                           │
       │                                              │
       │                                              │
       │  200 OK                                      │
       │  <─────────────────────────────────────────  │
       │  {"result": "..."}                           │
       │                                              │

Endpoints

POST /oauth/token

Obtains an access token for calling a protected service using the Client Credentials Grant.

POST /oauth/token

Headers

Content-Type: application/x-www-form-urlencoded

Parameters

Parameter	Type	Required	Description
grant_type	string	Yes	Must be "client_credentials"
client_id	string	Yes	OAuth client identifier (starts with svc_)
client_secret	string	Yes	OAuth client secret
profile	string	Yes	Profile identifier
environment	string	Yes	Environment name (e.g., "development", "production")
service_uuid	string	Yes	UUID of the target service

Example Request

curl -X POST https://automator.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=svc_abc123..." \
  -d "client_secret=def456..." \
  -d "profile=my-profile" \
  -d "environment=production" \
  -d "service_uuid=12345678-1234-1234-1234-123456789abc"

Success Response

200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7InNlcnZpY2VfdXVpZCI6IjEyMzQ1Njc4LTEyMzQtMTIzNC0xMjM0LTEyMzQ1Njc4OWFiYyIsInByb2ZpbGUiOiJteS1wcm9maWxlIiwiZW52aXJvbm1lbnQiOiJwcm9kdWN0aW9uIn0sInNjb3BlIjoic2VydmljZTpjYWxsIiwiaWF0IjoxNzAwMDAwMDAwLCJleHAiOjE3MDAwMDM2MDB9.signature...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "service:call"
}

Response Fields

Field	Type	Description
access_token	string	JWT access token for service authentication
token_type	string	Always "Bearer"
expires_in	integer	Token lifetime in seconds (always 3600 = 1 hour)
scope	string	Token scope (always "service:call")

Error Responses

400 Bad Request - invalid_request

{
  "error": "invalid_request",
  "error_description": "Missing required parameters"
}

Causes:

• Missing required parameter: grant_type, client_id, client_secret, profile, environment, or service_uuid
• Invalid profile (profile not found)
• Invalid environment (environment not found in profile)
• Invalid service_uuid (service not found in profile/environment)
• Service does not have OAuth enabled (auth_type is not "oauth")

400 Bad Request - unsupported_grant_type

{
  "error": "unsupported_grant_type",
  "error_description": "Only client_credentials grant type is supported"
}

Cause:

• grant_type parameter is not "client_credentials"

401 Unauthorized - invalid_client

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Causes:

• Invalid client_id (credential not found on service)
• Invalid client_secret (secret does not match)
• Client credential has been deleted