Skip to main content

​
Introduction

The Frontier API is a Connect RPC API that provides programmatic access to all Frontier features including user management, organization administration, billing, permissions, and more. The API is built on the Connect protocol, which provides efficient gRPC-compatible communication over HTTP/1.1 and HTTP/2.

​
Base URL

All API requests are made to the base URL: 
https://your-frontier-instance.com
The API is served on the Connect server port (default: 8002) with all endpoints under the /v1beta1 path prefix.
Replace your-frontier-instance.com with your actual Frontier deployment URL.

​
API Versioning

Frontier uses version-based URL paths. The current API version is v1beta1.
  • All API endpoints are prefixed with the version: /raystack.frontier.v1beta1.FrontierService/
  • The admin API uses: /raystack.frontier.v1beta1.AdminService/

​
Services

Frontier provides two main RPC services: 
raystack.frontier.v1beta1.FrontierService
FrontierService handles all user-facing operations including:
  • User and service user management
  • Organization and project operations
  • Group and role management
  • Billing and subscriptions
  • Permissions and policies
AdminService provides administrative operations for:
  • Platform configuration
  • System-wide permissions
  • Namespace management
  • Role definitions

​
Request Format

Frontier accepts requests in both JSON and Protocol Buffers formats. All requests must include the appropriate Content-Type header. 
curl -X POST https://your-frontier-instance.com/raystack.frontier.v1beta1.FrontierService/GetCurrentUser \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{}'

​
Content Types

  • application/json - JSON encoding (recommended for most clients)
  • application/proto - Protocol Buffer binary encoding
  • application/connect+json - Connect JSON encoding
  • application/connect+proto - Connect Protocol Buffer encoding

​
Response Format

All successful API responses return a JSON or Protocol Buffer object with the requested data. The structure varies by endpoint but follows consistent patterns.

​
Success Response

{
  "user": {
    "id": "8f7e7e3e-5c9c-4b9e-8f7e-7e3e5c9c4b9e",
    "name": "John Doe",
    "email": "[email protected]",
    "title": "Engineering Manager",
    "avatar": "https://example.com/avatar.jpg",
    "state": "enabled",
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-06-20T14:22:00Z"
  }
}

​
Common Response Fields

Many resources include these standard fields:
​
id
string
Unique identifier for the resource (UUID or custom ID)
​
name
string
Machine-readable name (slug format)
​
title
string
Human-readable display name
​
created_at
timestamp
ISO 8601 timestamp when the resource was created
​
updated_at
timestamp
ISO 8601 timestamp when the resource was last updated
​
metadata
object
Optional key-value pairs for custom data

​
Error Handling

Frontier uses Connect protocol error codes and provides detailed error messages. All errors follow a consistent structure.

​
Error Response

{
  "code": "unauthenticated",
  "message": "not authenticated",
  "details": []
}

​
HTTP Status Codes

Connect maps its error codes to HTTP status codes:
Connect CodeHTTP StatusDescription
ok200Success
canceled499Request canceled
invalid_argument400Invalid request parameters
not_found404Resource not found
already_exists409Resource already exists
permission_denied403Insufficient permissions
unauthenticated401Authentication required
resource_exhausted429Rate limit exceeded
failed_precondition400Precondition failed
internal500Internal server error
unavailable503Service unavailable

​
Common Error Codes

Here are the most common error codes you’ll encounter: 
{
  "code": "unauthenticated",
  "message": "not authenticated"
}

​
Domain-Specific Errors

Frontier provides specific error messages for domain operations:
  • Organization errors: org is disabled. Please contact your administrator to enable it
  • Billing errors: insufficient credits, already on same plan
  • Domain verification: required TXT record not found for domain verification
  • Invitation errors: invitation expired, user is already a member of the organization
  • KYC errors: customer portal changes not allowed: organization kyc completed

​
Rate Limiting

Frontier does not enforce global rate limits by default, but individual deployments may configure rate limiting. Check with your Frontier administrator for specific limits.
If you receive a resource_exhausted error, you’ve hit a rate limit. Wait before retrying.

​
Pagination

List endpoints support cursor-based pagination using the following query parameters:
​
page_size
integer
default:"50"
Number of results per page (max: 100)
​
page_num
integer
default:"1"
Page number to retrieve

​
Pagination Example

curl -X POST https://your-frontier-instance.com/raystack.frontier.v1beta1.FrontierService/ListUsers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 25, "page_num": 1}'

​
Health Checks

Frontier provides health check endpoints for monitoring:

​
Ping Endpoint

curl https://your-frontier-instance.com/ping
Response: 
{
  "status": "SERVING"
}

​
gRPC Health Check

curl -X POST https://your-frontier-instance.com/grpc.health.v1.Health/Check \
  -H "Content-Type: application/json" \
  -d '{"service":"raystack.frontier.v1beta1.FrontierService"}'

​
Service Reflection

Frontier supports gRPC reflection for discovering available services and methods:
  • Reflection v1: /grpc.reflection.v1.ServerReflection
  • Reflection v1alpha: /grpc.reflection.v1alpha.ServerReflection
Use tools like grpcurl or buf to introspect the API.

​
SDK Support

Frontier uses the Connect protocol, which has official client libraries for: You can also use standard gRPC clients with the generated protobuf definitions.

​
Next Steps

Authentication

Learn how to authenticate API requests

API Endpoints

Explore available API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us