Builder's guide · Section 6
Register your console as a writer
The administrator key from the installer is used for one job: managing writers. It cannot read or post the books. Use it to register your console and issue the console's own key.
Roles and scope
| Role | May | Use it for |
|---|---|---|
reader | Read the books of the companies in its scope | Dashboards, a reporting tool, an outside accountant's export |
poster | Read and write the books of the companies in its scope | Your console; an importer; an online-store connector |
administrator | Register, scope, retire writers; issue and revoke keys. No ledger access. | The operator's tooling only. Never the console. |
A reader or poster is scoped either to a list of companies or to all companies. Give each writer the narrowest scope that works. GAAPcore enforces some separation of its own: an administrator cannot change its own role or scope, and role changes need a different administrator.
The two calls
POST /v1/system/source-systems
X-Source-System: installer
Authorization: Bearer <administrator key>
Idempotency-Key: 0b8c…
{ "code": "console", "name": "Acme accounting console", "source_kind": "app",
"owner_name": "Pat Lee", "owner_email": "[email protected]",
"role": "poster", "company_ids": ["<company id>"] }
POST /v1/system/source-systems/console/credentials
→ { "id": "…", "secret": "ak_7Q2M4XKD9P1C_…", … }The secret is shown once. GAAPcore keeps only its SHA-256 hash. If you lose it, revoke that credential and issue a new one; even a replay of the same request returns the secret redacted.
Looking after the key
- Keep it in your server's secret store or environment, never in source control, and never in anything sent to a browser.
- Keys start with
ak_, so secret scanners can find a key that leaked. - Rotate without downtime: issue a second credential, deploy it, then revoke the old one. Revocation takes effect on the very next request, because GAAPcore checks credentials against the database on every call.
- Retiring a writer revokes all of its keys at once.
- When you add a company, an administrator widens the console's scope (
PUT /v1/system/source-systems/console/scope).