AI tools and connections · 5 min
Set up TellTell API access
Use the REST API and OpenAPI contract for scripts and integrations with delegated account access.
API addresses and contract
Open Settings → Connections → API → Setup for your account’s API addresses. Activity shows recent API and MCP operations. The REST API and MCP use the same TellTell permissions and account rules.
https://telltell-web-789927640952.us-east1.run.app/v1Download the OpenAPI 3.1.2 contract for routes, inputs, outputs, scopes, pagination, and errors. AI assistants normally use the /mcp endpoint described in the AI tools guide.
Authenticate with delegated OAuth
An Admin signs in and delegates selected account permissions to your integration. TellTell does not issue a static account API key or support machine identities/client-credentials grants in this release. Use an OAuth client library with authorization code and S256 PKCE.
- Discover the service
Read the REST protected-resource metadata at /.well-known/oauth-protected-resource/v1 on the API origin, then follow the advertised issuer metadata to its authorization, registration, token, and revocation endpoints.
- Register and authorize
Use supported client metadata or dynamic registration with exact callback addresses. Generate state and a PKCE verifier/challenge. Request only the scopes needed and use the full REST base URL ending /v1 as the OAuth resource. The Admin selects the TellTell account during consent.
- Use and protect tokens
Exchange the authorization code with the verifier. Send the access token in the Authorization: Bearer header, never a query string. Store credentials securely and keep them out of logs, source control, and chat. Request offline_access if refresh is needed; save rotated refresh tokens atomically.
Read and update records
Permissions cover People, teams/groups, fields/tags, ordinary settings, and jobs. Each category has read and write scopes. Lists default to 50 records with a maximum of 100 per page; follow the pagination returned by the endpoint.
- For every mutation, supply a unique Idempotency-Key of 16–200 characters. If a response is lost, retry the same request with the same key and unchanged payload.
- Read the current record before updating or deleting it and send its strong ETag in If-Match. Some multi-record operations use explicit version maps; follow the operation’s contract.
- A 412 means the record changed: read it again and reconsider the update. A 429 or 503 can be retried after Retry-After. Errors use structured problem details and a correlation ID.
Bulk previews and background jobs
An Admin must explicitly enable Allow bulk edits for the connection in Settings. Connector credentials cannot enable it themselves. Create a batch preview, inspect every page of targets and conflicts, then apply its exact identifier and digest. Scripts may preview and apply unattended once the Admin has enabled bulk access.
Asynchronous operations return 202 Accepted with a job location. Poll for progress and per-item errors, and use the cancellation operation when needed. Disabling bulk access or revoking the connection stops remaining items after the current atomic item. Completed changes and queued welcome email remain effective.
Review activity or revoke access
Use Settings → Connections → API → Activity to review recent operations. Manage the integration’s grant under Other tools → My account or All accounts; Grok Bot grants remain in the Grok Bot section. Revoke the connection in TellTell to remove account access immediately, or narrow its existing permissions. Adding privileges requires fresh consent.
For troubleshooting, retain the operation, HTTP status, and correlation ID. Do not include access tokens or directory payloads in support messages.