Skip to main content

​
Tilde auth.md

Applications with their own login system should use organization runtime identities and proxy tokens. Runtime identities can exist without a login account; managed linking connects a verified Tilde account later. Tilde supports anonymous, agent-first registration followed by an optional human claim. An agent can create a temporary Tilde organization without waiting for a person to sign in, use the returned agent API key, and later transfer the temporary workspace and its supported resources to a human-owned organization. This flow issues an API key directly. It is not an OAuth identity-assertion or token-exchange flow.

​
Actors and credentials

Tilde has two first-class actor types: human and agent. Credential form does not determine actor type by itself:
  • An API key authenticates as its owning runtime identity. A personal identity key remains human; an agent or installation key remains agent.
  • An OAuth access token is a bearer token and authenticates a human.
  • A request must carry exactly one credential form. Sending both x-api-key and Authorization: Bearer ... is rejected.
Organization proxy tokens provide explicit application delegation through X-Tilde-Proxy-Token and X-Tilde-Identity-Id. Tilde checks the token’s organization/capabilities and the effective identity’s current membership and resource permissions. The token issuer’s administrative roles are never combined with the identity’s permissions. Revoking a credential does not delete its runtime identity.

​
Resource visibility and ownership

Tilde authorization-bearing resources have two independent access planes:
  • Visibility controls discovery, listing, reading, and using the resource or its inherited content.
  • Ownership controls settings, membership, lifecycle operations, deletion, and grant management.
Each plane is either team or private. For a team-scoped resource, team admits current members of that team. For a personal resource without a team ID, it admits current members of the containing organization. private admits only explicitly granted Identity users and groups from the same tenant. Visibility and ownership never imply one another. An administrator or ownership grantee can manage a private resource without being able to read its content unless the visibility plane also admits them. Lists are filtered before pagination, and direct reads return not found or authorization errors when visibility is absent. New private resources retain an effective-creator grant. Tilde commits validated initial grants with the resource and prevents removal of the last private ownership grant. Group access follows current Identity membership, so removing a user from the group or tenant stops authorizing future requests.

​
Standard authorization operations

Authorization-bearing REST roots use the same operation family under their team or personal resource path:
The exact root path is published in the OpenAPI specification. Grant listing and mutation require ownership access. Re-adding or removing the same grant is idempotent, subject to the last-private-owner guard. Common-provider installations are authorization roots for provider bundles. Their policy is initialized from the source resource-server credential, then becomes the live policy inherited by the generated MCP, ChatKit, Signals, and reverse-proxy surfaces. Change a bound surface’s visibility, ownership, or grants through the installation endpoints; sibling surfaces do not copy policy from one another. Operations spanning independent roots require every applicable visibility check. For example, an MCP invocation requires both server and tool visibility, a signal delivery requires provider and rule visibility, and chat content requires the provider or agent plus session visibility. Billing entitlements and encryption key records are infrastructure, not shareable roots, so they do not expose these mode/grant operations. Resource secret use receives a server-only capability bound to the exact resource, action, and encryption scope after domain authorization.
These checks are enforced by the authenticated API and tenant-scoped persistence queries. Database row-level security is planned as an additional defense-in-depth layer; it is not currently the public authorization boundary.

​
Register anonymously

Send an unauthenticated request to:
Both fields are optional:
A successful response creates a temporary organization, team, and agent user. It returns:
  • org_id and team_id
  • api_key and api_key_id
  • claim_url and a six-digit claim_pin
  • claim_token_expires_at and expires_at
The temporary account lasts 24 hours. The initial claim URL lasts one hour. In production, the claim URL opens the human claim page under https://trytilde.ai/app/temporary-accounts/claim/ while the authenticated claim API remains on https://api.trytilde.ai.

​
Use the credential

Send the returned API key in the x-api-key header:
You can also connect to the Tilde Global MCP server at https://api.trytilde.ai/mcp with the same header. Call tilde_whoami first and use its team_id for team-scoped tools. Store the API key, claim URL, and PIN as secrets. Do not commit them, include them in logs, or send them to anyone other than the intended owner.

​
Refresh an expired claim URL

If the claim URL expires while the temporary account is still active, create a new one with the temporary API key:
The six-digit PIN does not change.

​
Hand off to a human

Give the intended owner the claim_url and claim_pin together. The human must:
  1. Sign in to Tilde.
  2. Select the organization that should own the temporary workspace.
  3. Open the claim URL.
  4. Enter the six-digit PIN on Tilde’s claim page.
  5. Wait for the page to confirm the transfer.
Five incorrect PIN attempts expire the current claim link. Generate a fresh link with the temporary API key if that happens. Claiming transfers the temporary team and supported resources into the human’s selected organization. Tilde revokes the temporary API key after a successful claim. Reconnect with a human bearer token, a human-owned API key, or a new team-scoped agent API key; call tilde_whoami again and update any organization-qualified URLs.

​
Discovery and API reference

  • OpenAPI: https://trytilde.ai/openapi.json
  • Agent context: https://trytilde.ai/llms.txt
  • Documentation: https://trytilde.ai/docs
  • OAuth protected-resource metadata: https://trytilde.ai/.well-known/oauth-protected-resource
  • OAuth authorization-server metadata: https://trytilde.ai/.well-known/oauth-authorization-server
  • AI Catalog: https://trytilde.ai/.well-known/ai-catalog.json
  • MCP server card: https://api.trytilde.ai/mcp/server-card
  • Legacy MCP server-card discovery alias: https://trytilde.ai/.well-known/mcp/server-card.json
Use a bearer token or human-owned API key for a human. Use a team-scoped agent API key for a deployed agent. An authorized installation agent can create and reconcile other agents without borrowing a human credential.