# CrewPass Partner API

> Scope-gated, consent-intersected, multi-tenant read API onto CrewPass crew, vessel, document, and compliance data. v1 is read-only plus webhooks, for management companies. Auth = partner API key (`cpk_live_*` / `cpk_test_*`) + HMAC-signed body. Access requires `granted ∩ consented` scopes and the crew being on your fleet (derived from your CrewPass employer account). Base URLs: `https://partners.crewpass.co.uk` (production), `https://crewpass-api-v2-dev-258178043395.europe-west4.run.app` (dev/sandbox). All endpoints under `/api/v2/`.

## Get started

- [Introduction](https://docs.crewpass.co.uk/partners/introduction.md): What the API is, what you can do, the access/consent model, base URLs.
- [Quickstart](https://docs.crewpass.co.uk/partners/quickstart.md): End-to-end management flow — vessels → fleet → crew lookup → profile/documents/compliance/download, with cURL, Python, and Node samples.
- [Authentication](https://docs.crewpass.co.uk/partners/authentication.md): API keys and the HMAC body signature, with signing helpers in Python, Node, and cURL.

## Guides (what you can do)

- [List your vessels](https://docs.crewpass.co.uk/partners/guides/vessels.md): GET /employers/me/vessels — the vessels on your account.
- [See your crew](https://docs.crewpass.co.uk/partners/guides/crew.md): The fleet roster (verification + background-check status + expiring counts), paging, and crew lookup by email.
- [Read a crew profile](https://docs.crewpass.co.uk/partners/guides/profiles.md): Base profile + consent-gated identity block + photo proxy.
- [Documents & downloads](https://docs.crewpass.co.uk/partners/guides/documents.md): List documents (issuer + verification status), the two-step branded download flow, and a "download all" example.
- [Check compliance](https://docs.crewpass.co.uk/partners/guides/compliance.md): What feeds compliance, overall_status, and the role / STCW / medical breakdown.
- [Background-check status](https://docs.crewpass.co.uk/partners/guides/background-checks.md): The standardised, provider-agnostic status vocabulary.

## Webhooks

- [Webhooks](https://docs.crewpass.co.uk/partners/webhooks.md): The change-feed — envelope, the outbound signing scheme (`v1=hmac(secret,"{ts}.{body}")`, which differs from request signing), event catalogue, payloads, retry/dead-letter, and a receiver-verification example.

## Reference

- [Rate limits](https://docs.crewpass.co.uk/partners/rate-limits.md): Per-partner token-bucket budgets and 429 handling.
- [Errors overview](https://docs.crewpass.co.uk/partners/errors.md): The error envelope and the full code catalogue.
- [invalid_api_key (401)](https://docs.crewpass.co.uk/partners/errors/invalid_api_key.md)
- [invalid_signature (401)](https://docs.crewpass.co.uk/partners/errors/invalid_signature.md)
- [api_not_enabled (403)](https://docs.crewpass.co.uk/partners/errors/api_not_enabled.md)
- [scope_not_granted (403)](https://docs.crewpass.co.uk/partners/errors/scope_not_granted.md)
- [scope_not_consented (403)](https://docs.crewpass.co.uk/partners/errors/scope_not_consented.md)
- [not_found (404)](https://docs.crewpass.co.uk/partners/errors/not_found.md)
- [partner_rate_limited (429)](https://docs.crewpass.co.uk/partners/errors/partner_rate_limited.md)
- [partner_mode_mismatch (403)](https://docs.crewpass.co.uk/partners/errors/partner_mode_mismatch.md)

## API reference

- [API reference overview](https://docs.crewpass.co.uk/partners/api-reference/overview.md): Where the spec lives and how to feed it to an AI agent.
- [OpenAPI spec (JSON)](https://docs.crewpass.co.uk/partners/api-reference/openapi.json): Full machine-readable contract.
- [OpenAPI spec (YAML)](https://docs.crewpass.co.uk/partners/api-reference/openapi.yaml): Same content, YAML.
- [Live spec (production)](https://partners.crewpass.co.uk/openapi.json): Always-current spec from the running API.

## Resources

- [Changelog](https://docs.crewpass.co.uk/partners/changelog.md): Versioning policy and release history.

## Optional

- [llms-full.txt](https://docs.crewpass.co.uk/partners/llms-full.txt): Every documentation page concatenated as one markdown file.