API Reference
CoreSDK has three API surfaces. None of them are called by SDK consumers directly — the SDK talks REST to cpod-backend, which proxies internally.
Surfaces at a Glance
| Surface | URL | Reachable from | Purpose |
|---|---|---|---|
| cpod-backend REST | https://api.yourdomain.com | Internet | SDK calls, OAuth flows, all app APIs |
| CoreSDK Control Plane | http://coresdk-cp:8080 | Internal network only | App registration, policy, JWKS, SCIM |
| CoreSDK Sidecar gRPC | [::1]:50051 | cpod-backend only (loopback) | Token validation, Rego, audit, jobs, secrets |
| Sidecar health/metrics | http://coresdk:9091 | Internal network | /healthz, Prometheus /metrics |
:8080 and :50051 are never called by your application code or the SDK. They are internal infrastructure. Only cpod-backend calls the sidecar. Only CI/ops pipelines call the Control Plane for bootstrap tasks.
cpod-backend — Public REST API
All SDK calls and OAuth flows go through cpod-backend. These are the endpoints your code uses:
OAuth
| Method | Path | Description |
|---|---|---|
GET | /oauth/authorize | Consent screen — redirect users here for PKCE flow |
POST | /v1/oauth/token | Issue access token (client_credentials / authorization_code / refresh_token) |
POST | /v1/oauth/introspect | Inspect token claims (RFC 7662) |
POST | /v1/oauth/revoke | Revoke a token (RFC 7009) |
GET | /v1/oauth/me/grants | List active grants for authenticated user |
App Management
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /v1/oauth/apps | Admin token | Register an OAuth app |
GET | /v1/oauth/apps | Admin token | List registered apps |
DELETE | /v1/oauth/apps/:id | Admin token | Delete an app |
POST | /v1/oauth/apps/:id/rotate-secret | Admin token | Rotate client secret |
Platform APIs
| Path | Description |
|---|---|
/v1/skills/* | Skill execution |
/v1/workflows/* | Workflow management |
/v1/projects/* | Project management |
/v1/users/* | User management |
/v1/files/* | File storage |
Control Plane — Internal Admin REST (:8080)
Used by cpod-backend internally and by ops/CI for bootstrap tasks. Never call from application code.
| Method | Path | Description |
|---|---|---|
POST | /oauth/token | Token issuance (proxied via cpod-backend) |
GET | /oauth/authorize | Consent redirect (proxied via cpod-backend) |
POST | /oauth/introspect | Token inspection (proxied via cpod-backend) |
POST | /oauth/revoke | Token revocation (proxied via cpod-backend) |
POST | /api/v1/apps | Register OAuth application |
GET | /api/v1/apps | List apps |
POST | /api/v1/apps/:id/rotate-secret | Rotate secret |
POST | /api/v1/scopes | Define custom scope |
GET | /api/v1/jwks | Public JWKS (RS256 public keys) |
PUT | /api/v1/tenants/:id/policy | Upload Rego policy bundle |
GET | /api/v1/audit | Query audit events |
GET | /api/v1/token-events | Token issuance/revocation stream |
/scim/v2/* | SCIM 2.0 federation |
Sidecar gRPC (:50051 — loopback only)
Called exclusively by cpod-backend. Reference only — your code never calls this.
| Service | Key RPCs |
|---|---|
AuthService | ValidateToken, Authorize, RevokeToken, RefreshToken, GetJwks |
PolicyService | Evaluate, DryRun, WatchPolicyUpdates (stream) |
AuditService | EmitAuditEvent, QueryAudit |
MaskingService | Mask, MaskString |
SecretsService | ResolveSecret |
JobService | SubmitJob, WatchJob, GetJobLogs, CancelJob |
FlagService | EvaluateFlag |
RateLimitService | CheckRateLimit, ResetRateLimit |
TenantService | ResolveTenant, ValidateIsolation |
Error Format
All cpod-backend endpoints return errors in this shape:
{
"error": "invalid_client",
"error_description": "client_secret is incorrect",
"status": 401
}OAuth errors follow RFC 6749 codes: invalid_client, invalid_grant, invalid_scope, unauthorized_client, unsupported_grant_type.
HTTP status codes are standard: 400, 401, 403, 404, 409, 422, 429, 500.