# 3D Services USA auth.md

> How an AI agent authenticates to the 3D Services USA agent API: quotes for 3D printed parts, and orders prepared for a person to pay.

## Audience

AI agents and automations acting for one existing 3D Services USA customer account. A key lets an agent price parts, upload and analyze CAD files, create and adjust quotes, rate shipping and issue a payment link. Reading the public site needs no credential.

## Registration

There is no self-registration for agents and no OAuth flow. The human account owner provisions the key:

1. Sign in at https://3dservicesusa.com/login with a customer account whose email address is verified.
2. Open https://3dservicesusa.com/dashboard/api-keys, name the key, choose its scopes and confirm with the account password.
3. Copy the token. It is shown once and cannot be recovered; a lost token is revoked and replaced.

An account may hold 5 active keys. Staff accounts cannot hold one.

Why a person issues it: a key spends money on the account's behalf (file storage, analysis, live carrier rates) and prepares orders billed to that account, so it comes from the person who pays. An agent that has no key should ask its user to create one at the page above; it cannot obtain one itself.

Supported method: a human-provisioned bearer API key. Provisioning page (signed-in, for the person): https://3dservicesusa.com/dashboard/api-keys.

## Using the credential

The token has the form `agk_<16 characters>.<43 characters>` (base64url alphabet). Send it on every request, in the header and nowhere else:

```
Authorization: Bearer agk_XXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

API base: https://3dservicesusa.com/api/agent/v1

Never put the token in a URL, a query string, a file name or a log. Every authentication failure (unknown, revoked, malformed, or the account is inactive) returns the same `401 UNAUTHORIZED`, so a failure does not say which keys exist.

## Scopes

| Scope | Grants |
| --- | --- |
| `quotes` | Estimate prices, upload and analyze files, create and reconfigure quotes. |
| `orders` | Rate and select shipping, and issue a payment link a person opens to pay. |

A call outside the key's scopes returns `403 FORBIDDEN_SCOPE`.

## Revocation

The owner revokes a key at https://3dservicesusa.com/dashboard/api-keys; it stops working on the next request. Every key on the account is revoked when the account password is changed or reset.

## Limits

Budgets are per account (all of its keys together) per UTC day, with a per-key burst limit per minute. A spent budget returns `429 RATE_LIMITED` with `Retry-After`; a site-wide ceiling returns `503 CAPACITY`.

| Action | Per day (account) | Per minute (key) | What counts |
| --- | --- | --- | --- |
| `request` | 3000 | 60 | Any authenticated call, reads included. |
| `estimate` | 300 | 30 | Geometry-only price estimates (no file, nothing stored). |
| `upload` | 40 | 10 | Upload URLs issued. |
| `upload_mib` | 1024 | - | Megabytes (MiB, rounded up per file) declared across all uploads. The upload URL enforces the exact size. |
| `analyze` | 40 | 10 | File analyses (re-analyzing an analyzed file is free). |
| `quote_create` | 20 | 5 | Quotes created. |
| `quote_update` | 200 | 20 | Quote reconfigurations (each one re-prices). |
| `shipping_rate` | 25 | 5 | Live carrier rate requests (repeating the same address within 6 hours is free). |
| `checkout_link` | 100 | - | Payment links issued. |

## Payment

The agent cannot pay. `POST /quotes/{id}/checkout-link` returns a link to the account dashboard; the account owner signs in there, reviews the order and pays. No payment credential or quote access token is ever given to the agent.

## Machine-readable descriptions

- Documentation: https://3dservicesusa.com/agents
- OpenAPI 3.1: https://3dservicesusa.com/agents/openapi.json
- API catalog (RFC 9727): https://3dservicesusa.com/.well-known/api-catalog
- Site summary for assistants: https://3dservicesusa.com/llms.txt