​

Institutional API

​

What the API is for

• Provisioning approved learners or employees into a Forex Masters organization.
• Managing organization invitations and membership lifecycle events.
• Synchronizing learner roster data with an LMS, student information system, CRM, or identity provider.
• Retrieving approved, organization-scoped learning and engagement records.
• Receiving lifecycle notifications for invitations, membership changes, and completion events.
• Building internal reporting experiences around authorized program activity.

​

Scope and access model

​

Available integration capabilities

​

Getting access

​

Authentication

• The production and test base URLs.
• Authentication mechanism and credential rotation procedure.
• Permitted organization identifier(s).
• Granted scopes and endpoint access.
• Rate-limit policy.
• Webhook signing secret and destination configuration.
• Named technical and security contacts.

​

Request expectations

Authorization: Bearer <institutional-access-token>
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
X-Request-ID: <your-correlation-id>

​

Organization isolation

​

Required practices

• Send only the organization identifier assigned to your integration.
• Treat every identifier as opaque; do not infer, enumerate, or modify identifiers from another tenant.
• Reconcile membership using stable external IDs where supported.
• Use idempotency keys for create, invite, and status-change operations.
• Keep your own correlation ID for audit and support investigation.
• Request the minimum scopes and fields necessary for the documented purpose.
• Remove or deactivate access promptly when a learner or employee leaves your program.

​

Membership lifecycle

1. Your source system identifies an eligible person.
2. Your server submits an approved provisioning or invitation request.
3. Forex Masters associates the person with the authorized organization after validation.
4. The person activates or signs in to their account.
5. Your system receives eligible lifecycle events through webhooks or scheduled reconciliation.
6. When eligibility ends, your system requests deactivation or removal in accordance with your organization’s policy.

​

Membership Lifecycle Process

1. Initiation: The Institution system requests to create or reconcile a membership via the Institutional API.
2. Validation: The API and Forex Masters validate the tenant, scope, and request, then return an accepted response.
3. Invitation: Forex Masters sends an access notification or invitation to the Learner.
4. Activation & Events: The Learner activates their account, triggering an authorized lifecycle event.
5. Webhook Delivery: The institution webhook verifies, records, and acknowledges the event with the Institution system.

​

Webhooks

• Membership invitation created, accepted, expired, or revoked.
• Organization membership activated, updated, or deactivated.
• Enrollment or cohort changes.
• Learning completion and certificate lifecycle events.
• Integration health or delivery failure notifications.

​

Webhook receiver requirements

1. Accept HTTPS requests from the configured Forex Masters delivery service.
2. Verify each message signature using the issued webhook secret.
3. Validate timestamps and reject stale or replayed messages where required.
4. Process events asynchronously.
5. Return a successful response only after durable receipt—not after full downstream processing.
6. Deduplicate events using the event ID supplied in the payload.
7. Maintain retry-safe handlers.

// Illustrative webhook handling pattern.
// Use the exact signature algorithm and headers supplied in your integration package.

export async function POST(request: Request) {
  const rawBody = await request.text()
  const signature = request.headers.get("x-forex-masters-signature")
  const eventId = request.headers.get("x-forex-masters-event-id")

  if (!signature || !eventId) {
    return new Response("Missing webhook headers", { status: 400 })
  }

  const isValid = verifyWebhookSignature({
    rawBody,
    signature,
    secret: process.env.FOREX_MASTERS_WEBHOOK_SECRET!,
  })

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 })
  }

  if (await hasProcessedEvent(eventId)) {
    return new Response(null, { status: 200 })
  }

  await persistWebhookForAsyncProcessing({ eventId, rawBody })

  return new Response(null, { status: 202 })
}

​

Error handling and retries

​

Security and privacy requirements

​

Do not

• Use API credentials to impersonate individual users.
• Export raw AI conversations, user dossier content, behavioral profiles, or broker credentials.
• Make promises of trading outcomes based on platform data.
• Use educational or engagement information as the sole basis for employment, admissions, credit, or investment decisions.
• Forward API responses to unapproved third parties.
• Treat test data as non-sensitive unless explicitly designated and approved as synthetic.

​

Implementation checklist

​

Support and change management

• Access requests and scope changes.
• Credential rotation or suspected credential exposure.
• Webhook delivery problems.
• Data subject, deletion, or retention inquiries.
• New integration use cases.
• Production incidents and service-impacting issues.

​

Related resources