# DripTell auth.md

This document is for agents and developers connecting to DripTell on behalf of an authorized workspace user.

## Available authentication methods

### Public REST API

The DripTell Public API uses workspace-scoped API keys.

1. Sign in to https://app.driptell.com.
2. Open the workspace API key settings.
3. Create a key with only the permissions needed for the task.
4. Send the credential in the HTTP header:

```http
Authorization: Bearer <workspace-api-key>
```

The REST API base URL is https://app.driptell.com/api/v1. Verify a key with `GET https://app.driptell.com/api/v1/verify`.

### MCP for agents

DripTell's MCP server uses OAuth 2.0 Authorization Code with PKCE.

- Agent registration identity type: `anonymous`
- Registration credential type: `oauth_client_id`
- MCP endpoint: https://app.driptell.com/api/mcp
- Authorization server metadata: https://driptell.com/.well-known/oauth-authorization-server
- Protected resource metadata: https://driptell.com/.well-known/oauth-protected-resource
- Dynamic client registration: https://app.driptell.com/api/mcp/oauth/register
- Authorization: https://app.driptell.com/mcp/authorize
- Token exchange: https://app.driptell.com/api/mcp/oauth/token
- Revocation: https://app.driptell.com/api/mcp/oauth/revoke

Register a public OAuth client by sending:

```http
POST https://app.driptell.com/api/mcp/oauth/register
Content-Type: application/json
```

```json
{
  "client_name": "Your agent name",
  "redirect_uris": ["https://agent.example/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}
```

The response contains the `client_id`. Use it with a fresh PKCE `S256` code challenge at the authorization endpoint. Exchange the returned authorization code at the token endpoint with the matching code verifier. A client secret is not issued because agents register as public PKCE clients.

The user must complete the DripTell authorization screen. Agents must not bypass consent, request broader scopes than the task needs, or move a token between workspaces.

## Credential handling

- Never place a token in a URL, browser bundle, generated file, log, analytics event, or chat response.
- Store credentials in a secret manager or protected server environment.
- Treat HTTP 401 and 403 as a signal to stop and re-authorize, not to retry with unrelated credentials.
- Revoke credentials when an integration is removed or compromised.

## Documentation

- Human API guide: https://driptell.com/developers
- OpenAPI: https://driptell.com/openapi.json
- MCP server card: https://driptell.com/.well-known/mcp/server-card.json