Provider Credentials Wiki
Developer guide for the provider catalog and credential store — start here.
This is the developer wiki for the Provider Credentials Service: the single source of truth for which machine-translation and AI providers exist and which credentials to call them with. It stores the vendor/provider catalog (schemas, capabilities, technical notes) and encrypted credentials on three ownership levels — user, organization, platform — and resolves the effective credential for a request via the fixed chain USER → ORGANIZATION → PLATFORM. The service never calls an external provider itself.
You integrate over plain HTTP, on one of two planes: the user plane (/v1/*, short-lived exchange JWTs from the identity provider) for humans and product backends, and the service plane (/internal/v1/*, OAuth 2.0 client-credentials tokens with per-group scopes) for trusted microservices. Secrets are stored encrypted and always returned masked; plaintext leaves the service only through resolve and the operator reveal.
Every page in this wiki is written for integrators: you call endpoints, you never read our source. Behavior described here is backed by the API contract and the test suite; the cookbook scenarios each mirror a named test.
Pick your path
| You are… | Start here |
|---|---|
| New — I just want an authenticated call | Quickstart |
| Building a credentials UI for end users | Provider Schemas, then Store your first credential |
| An organization admin sharing one key with the team | Organization Credentials, then Share an org credential |
| A translation runtime that needs keys to call providers | Resolve Chain, then Resolve credentials |
| An operator running the admin panel or scripts | Internal Admin API, Reveal, Audit Events |
| Wiring authentication | User Plane Tokens · Service Plane Tokens |
API reference
Interactive ReDoc is served by the API itself, in three locales: English, Ukrainian, Russian. For a one-line summary of all operations with links to their owning wiki pages, see Endpoints Index.
Folder map
00 Getting started — Quickstart · Core Concepts · Errors and Conventions · Rate Limits
01 Catalog — Vendors and Providers · Provider Schemas · Full Catalog
02 Credentials — Personal Credentials · Organization Credentials · Defaults and Lifecycle · Credential Status
03 Resolve — Resolve Chain
04 Admin — User Plane Admin · Internal Admin API · Reveal · Audit Events
05 Integration — User Plane Tokens · Service Plane Tokens
07 Cookbook (runnable scenarios, each mirrored by a test) — Browse the catalog · Store your first credential · Rotate a secret · Manage defaults · Share an org credential · Resolve credentials · Administer platform credentials · Reveal a credential · Read the audit trail · Handle validation errors
08 Reference — Endpoints Index · Error Codes · Glossary
Two conventions to internalize before anything else
Every non-2xx response is one envelope: {"error": {"code", "message", "details", "correlation_id"}} — branch on code, never on prose. And every mutation of a stored credential demands the record's current version (optimistic locking) — read, then write. Details in Errors and Conventions.