Authentication

gospace services accept JWT bearer tokens issued to users or service principals, and workspace-scoped API keys. All credentials are validated by the shared REST authorizer and propagate workspace scope to downstream handlers.

Service principals

1. Create a service principal in the Platform (Account → Developer).
2. Record the client_id, client_secret, and workspace_id.
3. Exchange the credentials for an access token:

POST https://api.gospace.ai/v1/auth/token
Content-Type: application/json

{
  "client_id": "spn_123",
  "client_secret": "...",
  "workspace_id": "wrk_456",
  "scope": "workspace:read data:read agents:run"
}

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Send Authorization: Bearer <access_token> and include x-workspace-key: <workspace_id> if the token does not embed it.

Interactive sessions (bearer tokens)

Use the auth public API to refresh or verify tokens obtained via login/register (email or Google/GitHub).

POST https://api.gospace.ai/v1/auth/token
Content-Type: application/json

{
  "refresh_token": "<refresh_token>"
}

Response (trimmed):

{
  "success": true,
  "data": {
    "user": { "user_id": "usr_123", "email": "ops@example.com" },
    "access_token": "eyJhbGciOi...",
    "refresh_token": "..."
  }
}

Use Authorization: Bearer <access_token> with any public API.

Related endpoints:

• POST /v1/auth/login + POST /v1/auth/verify (email magic links)
• GET /v1/auth/login/google and /login/github (social)
• GET /v1/auth/me / PATCH /v1/auth/me (profile)
• GET|POST|PATCH|DELETE /v1/auth/admin/users and /admin/roles

API keys (workspace-scoped)

API keys are tied to a workspace and align with platform usage policies.

Create and manage keys (requires a bearer token):

POST https://api.gospace.ai/v1/auth/api-key
Authorization: Bearer <access_token>

Response:

{
  "success": true,
  "data": { "api_key": "key_<shard>.<LOC>.<WORKSPACE>.<uuid>" }
}

Use the key on any service:

GET /v1/system/workspaces
Host: api.gospace.ai
x-api-key: key_abc.UK.WORKSPACE123.abcd1234

Generated keys are workspace-scoped. If you need to force a workspace (rare), include x-workspace-key: <workspace_id> alongside x-api-key.

List or delete keys:

• GET /v1/auth/api-key
• DELETE /v1/auth/api-key/{key_id}

Request headers

Rotation & safety

• Bearer tokens expire after 60 minutes; refresh before expiry.
• Rotate client secrets and API keys regularly; revoke compromised credentials from the console.
• Use separate principals per environment (dev, staging, production) to keep scopes tight.