# Getting a SimpleDock credential

This file is for AI agents. It covers three cases:

1. **The person already has a SimpleDock account** → connect over OAuth.
2. **They have an API key** → send it as a bearer token.
3. **They have no account** → create one for them with one request (below), set it up, and have them confirm their email.

## 1. Existing account: OAuth

Add the MCP server `https://simpledock.ai/api/v1/mcp` to your client. Its first `401`
carries `WWW-Authenticate: Bearer resource_metadata="https://simpledock.ai/.well-known/oauth-protected-resource"`;
follow it to the authorization server, register (Dynamic Client Registration or a
Client ID Metadata Document), and have the person sign in and approve. PKCE (S256)
is required.

## 2. API key

`Authorization: Bearer sd_live_…`. Keys are created in Settings → API and work on
every plan.

## 3. No account: sign them up

Ask the person for their **email address, company name, facility name, and the
facility's timezone** before calling. Use their real work email: they have to read
it to finish, and disposable inboxes are refused.

```http
POST https://simpledock.ai/api/v1/agent/signup
Content-Type: application/json

{
  "email": "pat@acme-logistics.com",
  "name": "Pat Rivera",
  "organizationName": "Acme Logistics",
  "location": {
    "name": "Acme Dallas DC",
    "address": "1200 Commerce St",
    "city": "Dallas",
    "state": "TX",
    "zip": "75202",
    "timezone": "America/Chicago"
  },
  "source": "your-agent-name"
}
```

`201 Created` returns `data` with:

- `organization`, `location` (with `bookingPageUrl`)
- `credentials`: a standard OAuth token response (`access_token`, `refresh_token`,
  `expires_in`, `scope`) plus `token_endpoint` and `client_id`
- `mcp.url`: send `Authorization: Bearer <access_token>` there
- `verification`: what to tell the person
- `nextSteps`

The account works immediately. Set it up over MCP with one `manage_location`
call with `action: "set_up"` (weekly hours, appointment types, and doors, which
refer to types by name). Its `bookingPage.problems` is empty once carriers can
book. Fine-tune with `manage_location` `update_details` and
`manage_booking_question` `create`.

### Refreshing

The access token lasts 60 minutes. Refresh it before it expires:

```http
POST https://simpledock.ai/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=sd_rt_…&client_id=simpledock-agent-signup
```

Every refresh returns a new refresh token; the old one stops working. Presenting a
used refresh token again revokes the whole connection.

### Claiming: the person confirms their email

SimpleDock emails the person a confirmation link. Have them open that email and
click **Confirm and claim account**. That also sets their password.

The same email contains a six-digit code. **REST only, not available over MCP.**
If you can read the person's email, POST the code:

```http
POST https://simpledock.ai/api/v1/agent/account/verify
Authorization: Bearer <credentials.access_token>
Content-Type: application/json

{ "code": "042917" }
```

The signup tokens (`sd_at_` access and `sd_rt_` refresh) refresh, so this call
does not need an API key. API keys are created in Settings → API, not over MCP.

Five wrong codes lock the email; resend to get a new one.

If the email didn't arrive, resend it with `POST https://simpledock.ai/api/v1/agent/account/resend-verification` or
MCP `manage_account` with `action: "resend_verification_email"`. Poll `GET https://simpledock.ai/api/v1/agent/account` (or
`get_account_status`) at most once a minute to see whether they've confirmed. Wait
for them; don't loop.

**Until the email is confirmed**, everything works except what reaches people
outside the account:

- No appointment emails or texts to carriers, drivers, or alert recipients
- The booking page isn't indexed by search engines
- No teammate invites and no long-lived API keys

An account nobody confirms is deleted after 7 days.

### Errors

The standard envelope, `{ "error": { "code", "message", "details" } }`:

| Status | `code` | `details.reason` | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | | Fix the field named in `details`. |
| 409 | `conflict` | `account_exists` | They already have an account: use OAuth (case 1). |
| 409 | `conflict` | `registration_pending` | An agent already started one; the confirmation email was re-sent. Have them confirm, then use OAuth. |
| 429 | `rate_limited` | | Wait `Retry-After` seconds. |

After signup, calls can return `402 payment_required`: `manage_location` `create`
for a second location on Free, or a Pro feature such as analytics.

## Revoking

The person sees this connection under Settings → AI assistants and can disconnect
it there. You can end it yourself with RFC 7009 revocation at
`https://simpledock.ai/api/oauth/revoke` (send the refresh token and `client_id`).