API Reference

All endpoints are prefixed with the SP base URL. Authenticate with X-API-Key header or hap-session cookie.

Quick links

SP CoreAuthProfilesGroupsAttestationsOther

SP Core

Attestation signing and verification

GET/api/sp/pubkeyPublic

Get SP Ed25519 public key

Response

{ "publicKey": "hex-string" }
POST/api/sp/attestAPI key, session, or external token

Sign attestation (group-managed or external mode)

Group-managed mode (group_id provided): SP verifies domain authority via group membership. External mode (no group_id): caller claims domain, SP authenticates but does not verify authority.

Request body

{
  "profile_id": "payment-gate@0.3",
  "path": "payment-routine",
  "domain": "finance",
  "did": "did:key:alice",
  "group_id": "demo-team",          // optional: omit for external mode
  "gate_content_hashes": { ... },
  "execution_context_hash": "sha256:...",
  "frame": { ... },                  // or "frame_hash": "sha256:..."
  "ttl": 3600                        // optional
}

Response

{
  "attestation_id": "sha256:...",
  "frame_hash": "sha256:...",
  "domain": "finance",
  "blob": "base64url-encoded",
  "expires_at": 1772495020,
  "status": "active",
  "attested_domains": ["finance"],
  "required_domains": ["finance"]
}
POST/api/sp/verifyPublic

Verify an attestation blob

Request body

{ "blob": "base64url-encoded" }

Response

{ "valid": true, "payload": { ... } }

Auth

Registration, sessions, and key management

POST/api/auth/registerPublic

Register a new user and get an API key

Request body

{ "name": "Alice", "email": "alice@example.com" }

Response

{
  "user": { "id": "...", "name": "Alice", "email": "...", "did": "did:key:..." },
  "apiKey": "uuid"    // shown once, never retrievable again
}
POST/api/auth/sessionX-API-Key header

Create a browser session (sets hap-session cookie)

Sets HttpOnly cookie. Use for browser-based access.

Response

{ "user": { "id": "...", "name": "...", "email": "...", "did": "..." } }
POST/api/auth/renew-keySession or API key

Rotate API key (old key invalidated immediately)

Response

{ "apiKey": "new-uuid" }
POST/api/auth/logoutSession cookie

End session and clear cookie

Response

{ "ok": true }

Profiles

Agent execution profiles (protocol and community)

GET/api/profilesPublic

List and search profiles

Query parameters

?type=protocol|community  &author={userId}  &q={search}

Response

{ "profiles": [{ "id", "version", "description", "paths" }] }
POST/api/profilesAPI key or session

Create a community profile

Profile ID is auto-namespaced. Immutable once published. TTL max 24h.

Request body

{ "profile": { ...AgentProfile JSON } }

Response

{ "profile_id": "community/{userId}/{name}@{version}", "created_at": ... }
GET/api/profiles/{id}Public

Get full profile definition

Response

{ ...full AgentProfile }

Groups

Authorization mapping for domain authority

GET/api/groupsAPI key or session

List user's groups with their domains

Response

{ "groups": [{ ...group, "myDomains": [...], "isAdmin": bool }] }
POST/api/groupsAPI key or session

Create a new group

Request body

{ "name": "Backend Team" }

Response

{ "group": { ... }, "inviteCode": "abc12345" }
POST/api/groups/joinAPI key or session

Join a group via invite code

Request body

{ "inviteCode": "abc12345" }

Response

{ "group": { ... }, "member": { ... } }
GET/api/groups/{id}API key or session (member)

Group detail with all members

Response

{ "group": { ... }, "members": [...], "isAdmin": bool }
PUT/api/groups/{id}/members/{userId}API key or session (admin)

Assign domains to a group member

Request body

{ "domains": ["engineering", "security"] }

Response

{ "member": { ... } }
DELETE/api/groups/{id}/members/{userId}API key or session (admin)

Remove a member from the group

Response

{ "ok": true }
POST/api/groups/{id}/inviteAPI key or session (admin)

Regenerate invite code

Request body

{ "expiresIn": 86400 }   // optional, seconds

Response

{ "inviteCode": "...", "expiresAt": ... }

Attestations

Query attestation status

GET/api/attestationsPublic

Get attestations by frame hash

Query parameters

?frame_hash=sha256:...

Response

{ "frame": { ... }, "attestations": [{ "domain", "blob", "expiresAt" }] }
GET/api/attestations/mineAPI key or session

User's own attestations with status filtering

Query parameters

?status=active|pending|expired

Response

{ "attestations": [{ "frameHash", "profileId", "path", "status", ... }] }
GET/api/attestations/pendingPublic

Frames pending attestation for a domain

Query parameters

?domain=finance

Response

{ "pending": [{ "frameHash", "missingDomains", ... }] }

Other

Utility endpoints

GET/api/usersPublic

List demo users (API keys omitted)

Response

{ "users": [{ "id", "name", "email", "did" }] }
GET/api/healthPublic

Server health check

Response

{ "status": "ok", "timestamp": "..." }