Onboarding API reference

Provision applications and originate applicant sign-in links from your own systems. All requests are HTTPS POST with a JSON body and a JSON response. There are two endpoints.

Before you start

Three things are arranged with Aurora Edge before you can call the API.

A tenant, with at least one intake pair configured and a label attached. See Core concepts.
An API key for that tenant. The secret is shown once at issue.
A test tenant, if you want somewhere to integrate against that is not your live case book. There is no self-serve sandbox, so ask for one during onboarding.

Base URL

base url

https://aegis-api.theauroraedge.com

Authentication

Send your key as a bearer token on every request.

header

Authorization: Bearer aegis_<key-id>_<secret>

Your key is tenant-scoped: it can create applications for your organisation only, and cannot read other applicants or change settings. Key issuance, rotation, and revocation are covered in Administration.

This is a server-to-server API

Cross-origin requests are not enabled and OPTIONS is rejected, so the API cannot be called from a browser or a mobile client by design. Keep the secret on your server. Anyone holding it can create applications and mint sign-in links for your tenant.

POST /v1/login-sessions

Provision an application and return a ready-to-use sign-in link.

Field	Type	Description
emailrequired	string	The applicant's email. Also the idempotency key. Normalised to lowercase, must contain `@`, maximum 320 characters.
companyName	string	Display name for the application. Defaults to the email address.
externalRef	string	Your reference, such as an order or case id. Participates in idempotency and lets you reconcile later.
labelId	string	Which intake to use. Optional only if your tenant has exactly one active intake.
redirectPath	string	Where to land the applicant after sign-in. Must be one of `/upload-documents`, `/status`, `/form-parser`, `/dashboard`. Values outside this list are not applied, and the applicant lands on the default entry point.

Response 200

json

{
  "loginUrl": "https://aegis-gateway.theauroraedge.com/auth/sso?ticket=...",
  "clientId": "a1b2c3d4-...",
  "expiresAt": "2026-07-24T12:30:00.000Z"
}

Field	Type	Description
loginUrl	string	The single-use sign-in link. Treat it as a credential: redirect to it, do not store, log, or render it into a page.
clientId	string (uuid)	The application's permanent identifier, and your join key back to Aegis. It is stable for the life of the application and is returned unchanged by an idempotent repeat. Persist it against your own record.
expiresAt	string (ISO 8601)	When the link stops working. Read this value rather than hardcoding a duration, so a future change to the lifetime does not silently break your integration.

The link is single-use and expires two minutes after it is issued

It is designed to be handed to a user who is already waiting, for example after a form submission on your own site. It is not suitable for putting into a queued email or a batch job. To email an applicant, see the recipe in Integration guide.

bash

curl -sS -X POST "https://aegis-api.theauroraedge.com/v1/login-sessions" \
  -H "Authorization: Bearer aegis_<key-id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cfo@acme-partner.example",
    "companyName": "Acme Partner FZ-LLC",
    "externalRef": "ORDER-88213"
  }'

POST /v1/applications

Provision without minting a link. Use this when your compliance team will contact the applicant, or when you only need the identifier now.

Body: email (required), companyName, externalRef, labelId, with the same rules as above.

Response 200

json

{ "clientId": "a1b2c3d4-...", "status": "pending" }

The returned status is the application's position in the onboarding lifecycle, using the same vocabulary your compliance team sees in the dashboard. The full set of statuses and the moves permitted between them are in Onboarding lifecycle.

Idempotency

Provisioning is idempotent per applicant. Sending the same email and externalRef again returns the existing clientId instead of creating a duplicate application. Always send a stable externalRef, and treat it as immutable once an applicant exists: changing it changes the identity of the request.

Because of this, a retry after a timeout is safe and will not create a duplicate.

Errors

Errors are JSON: { "code": "...", "message": "..." }.

HTTP	Code	Meaning
400	invalid-argument	Missing or invalid `email`, or an unknown `labelId`.
400	failed-precondition	The intake is not usable: not part of your tenant, or it has no fields or scoring rules yet. Also returned when no `labelId` was supplied and your tenant does not have exactly one active intake.
401	unauthorized	Missing, malformed, revoked, or invalid API key.
403	permission-denied	Your tenant is suspended, or that application is locked.
404	not-found	Unknown endpoint.
405	method-not-allowed	Anything other than POST, including `OPTIONS`.
410	failed-precondition	The application was erased under a data-governance request and cannot be recreated.
429	resource-exhausted	Rate limit exceeded. Back off and retry.
500	internal	Transient. Retry with backoff.

Rate limits

Limit	Scope
60 requests per minute	Per API key
240 requests per minute	Per source IP address

Both return 429 with code resource-exhausted. Retry with exponential backoff.

Versioning

The API is versioned in the path (/v1). Additive changes stay backward-compatible within a version. Breaking changes ship under a new version with a deprecation window.

There is no read endpoint

The API provisions applications; it does not report on them. There is no GET and no status callback, so outcomes are reconciled through the compliance dashboard. Design your integration around this from the start: see the reconciliation guidance in Integration guide.