SECURITY
Authentication and permissions
Tenant-scoped machine credentials authenticate the sending forwarder and define which Ocean API operations it may call.
Bearer credentials
Pass the credential in Authorization: Bearer <token>. Current tokens have the foc_ prefix followed by 64 lowercase hexadecimal characters.
Foryn stores a hash of the token, not the raw secret. The credential binds the tenant and source system; never submit a tenant ID in the JSON body.
Production issuance, rotation, and revocation require coordinated onboarding. A local-development provisioning script exists but is not a public API.
Scopes
| Permission | Applicable API | Meaning |
|---|---|---|
| intake | POST /api/ocean/v1/bookings | Submit qualified booking events |
| intake | POST /api/ocean/v1/messages | Submit supported EDI/JSON event envelopes |
| resolution | POST /api/ocean/v1/exceptions/{id}/resolutions | Record optional resolution |
| allowEquivalent (credential flag) | Booking qualification | Permits EQUIVALENT_CONFIRMED when separately supported by source evidence |
Operational rules
- Keep secrets in your approved vault, not source code, browser storage, logs, tickets, or agent prompts.
- Use HTTPS to the onboarding-provided API hostname. Do not infer API availability from this public docs site.
- 401 means invalid/missing token format; 403 means the credential was not found, was revoked, or lacks the required scope.
- 429 RATE_LIMITED means a per-client, per-credential or failed-authentication allowance was exceeded. Wait for the Retry-After seconds before retrying; repeated invalid tokens lock out the client address temporarily. Retries of the same eventId remain safe.
- Send Content-Type: application/json. Other content types return 415, and bodies over 64 KiB return 413.
- Request correlation uses x-request-id. Send an ID of 8 to 64 letters, digits, dots, underscores or hyphens to have it echoed; any other value is replaced with a generated ID. Forward the exact returned ID to your support contact when investigating failures.
- Do not treat caller-supplied operator attribution as a verified Foryn human identity.
API v1 · Fictional examples · Production access requires coordinated onboarding · OpenAPI contract ↗