API reference

Automate Fidwyn from your own pipelines: a versioned REST API, application-to-application credential brokering, signed webhooks, and SCIM provisioning. The shapes below are representative. The authoritative, versioned endpoint reference ships in the product and the developer portal.

1 · Issue a token ¶

Every call is made as a service identity. Create a dedicated user for the integration and place it in an Access Group that grants exactly the rights the integration needs and no more, then issue that identity a role-scoped API token from the console. Treat the token as a secret: store it in your own vault, and rotate or revoke it from the same screen.

2 · Authenticate ¶

The API is versioned so an integration does not break on upgrade. Send the token as a bearer credential over TLS:

Authorization: Bearer <api-token>
Accept: application/json

3 · Broker a credential (A2A) ¶

A machine client receives a scoped proxy token; the secret is revealed once and every fetch is audited. A client can be constrained with an optional user token, MFA, IP restriction, and an approval gate. Representative exchange:

# request a brokered secret (representative shape)
POST /api/v1/a2a/checkout
{ "client_id": "ci-deploy", "secret_ref": "win-build-01/svc-deploy" }

# response
{ "value": "<shown once>", "expires_in": 300, "audit_id": "a1b2c3" }

4 · Subscribe to webhooks ¶

Webhooks are delivered over HTTPS and signed with an HMAC secret; configure the events, retry limit, and inspect a full delivery-and-attempt log. Verify the signature before trusting a payload:

X-Fidwyn-Signature: sha256=<hmac>
# body is the exact bytes signed; recompute and compare

5 · Provision users (SCIM) ¶

Provision and deprovision users and groups from your IdP so access follows the joiner-mover-leaver lifecycle automatically. CI/CD pipelines can also pull a just-in-time secret at run time, so no long-lived credential sits in a repository.