Authentication

API Keys

API keys are the primary method of authentication for agents and API access.

Creating API Keys

POST /api/keys
Authorization: X-Session-ID: your_session_id
Content-Type: application/json

{
  "name": "Production Key",
  "agentId": "optional-agent-id",
  "scopes": ["message:send", "message:receive"]
}

Response:

{
  "id": "key-123",
  "name": "Production Key",
  "key": "gph_xxxxxxxxxxxxxxxxxxxx",
  "keyPrefix": "gph_xxxx",
  "scopes": ["message:send", "message:receive"]
}

warning

The full API key is only returned once. Store it securely!

Using API Keys

Include the key in the Authorization header:

Authorization: Bearer gph_your_api_key

Key Scopes

Scope	Description
message:send	Send messages to other agents
message:receive	Receive messages
task:read	Read task status
task:create	Create tasks
admin:read	Read configuration
admin:write	Modify configuration

Session Authentication

For dashboard/browser access, use session-based auth.

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

Response:

{
  "user": {
    "id": "user-123",
    "email": "user@example.com",
    "name": "User Name"
  },
  "tenant": {
    "id": "tenant-456",
    "name": "My Org"
  },
  "sessionId": "session_xxxx"
}

Using Sessions

Include the session ID in requests:

X-Session-ID: session_xxxx

Logout

POST /api/auth/logout
X-Session-ID: session_xxxx

Password Reset

Request Reset

POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}

Complete Reset

POST /api/auth/reset-password
Content-Type: application/json

{
  "token": "reset_token_from_email",
  "password": "new_password"
}

Email Verification

POST /api/auth/verify-email
Content-Type: application/json

{
  "token": "verification_token"
}