One read-only contract, delivered over HTTP and over MCP

Authentication

• Send the credential as Authorization: Bearer <credential>.
• A credential carries well over 256 bits of cryptographically secure randomness.
• The raw secret is displayed exactly once, at creation, and can never be retrieved again.
• Only a one-way hash is stored. A non-secret key identifier is kept for lookup and display.
• Never place a credential in a URL, a query string, a log, an analytics event or browser storage.
• These are server-to-server credentials. There is no browser workflow and no wildcard CORS origin.
• Rotation issues a second credential with a controlled overlap window; revocation takes effect immediately.
• An ordinary user session token is never an API key, and no service-role credential is ever exposed.

Scopes

directories.read

Read private workspace directory records that are in scope for this client.

directories.schema.read

Read the active schema of an in-scope private directory.

profiles.read

Read private profile records in an in-scope directory.

profiles.search

Search private profiles within an in-scope directory.

profiles.public_fields.read

Read properties whose visibility class is public.

profiles.private_fields.read

Read properties whose visibility class is private, workspace or assigned. Requires explicit private-data permission and a property that permits machine access.

catalogue.directories.read

Read the Platform approved catalogue directory projection.

catalogue.profiles.read

Read the Platform approved catalogue profile projection.

catalogue.search

Search the Platform approved catalogue projection only.

A sensitive property requires both a client scope that allows it and a property configuration that permits machine access. Delivery is read only: there is no write, no import, no moderation, no publication, no invitation, no role change and no key administration through the API or MCP.

Requests and responses

curl https://bobbydirectory.com/api/v1/directories/example-directory/profiles?limit=25 \
  -H "Authorization: Bearer bdk_0000000000000000.EXAMPLE_ONLY_NOT_A_REAL_CREDENTIAL"

{
  "data": [
    { "handle": "example-record", "label": "Example Record", "updatedAt": "2026-01-01T00:00:00Z" }
  ],
  "pagination": { "next_cursor": "eyJ...opaque...", "page_size": 25 },
  "request_id": "0f2f6a54-0000-4000-8000-000000000000",
  "api_version": "v1"
}

{
  "error": { "code": "forbidden", "message": "This credential does not carry the required scope." },
  "request_id": "0f2f6a54-0000-4000-8000-000000000000"
}

• 200 for a successful read, 400 malformed, 401 missing or invalid credential, 403 missing scope.
• 404 for anything unknown, private or out of scope, so nothing can be enumerated.
• 405 for an unsupported method, with an Allow header.
• 429 when a rate limit is reached, with retry guidance. 503 when the delivery switch is off.
• No SQL text, table name, function name, stack trace or internal identifier is ever returned.

MCP

POST https://bobbydirectory.com/mcp
Authorization: Bearer bdk_0000000000000000.EXAMPLE_ONLY_NOT_A_REAL_CREDENTIAL
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

tools/list reveals only the tools this credential may call. Tool inputs are strict and unknown fields are rejected. There are no mutation tools, no SQL tool, no URL fetch tool, no filesystem tool and no credential-management tool.