> ## Documentation Index
> Fetch the complete documentation index at: https://forexmasters.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Institutional API

> A controlled integration interface for institutions, colleges, and enterprise partners to connect Forex Masters learning, intelligence, and workforce workflows.

# Institutional API

The Forex Masters Institutional API enables approved organizations to connect their internal systems with Forex Masters’ education, trader-development, and institutional intelligence workflows.

It is designed for colleges, training organizations, workforce-development programs, broker partners, and enterprise learning teams that need governed access to learner provisioning, progress visibility, and selected platform data—without exposing sensitive trading, behavioral, or AI context unnecessarily.

<Note>
  Institutional API access is provisioned through an approved business engagement. It is not a self-service public trading or broker-execution API.
</Note>

## What the API is for

Use the Institutional API to support organization-level workflows such as:

* 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.

<CardGroup cols={3}>
  <Card title="Colleges & academies" icon="graduation-cap">
    Connect student enrollment, cohort administration, and curriculum progress to your existing education systems.
  </Card>

  <Card title="Enterprise teams" icon="building">
    Manage employee access, learning programs, and approved organizational reporting from a central workflow.
  </Card>

  <Card title="Strategic partners" icon="handshake">
    Support governed integrations for approved distribution, education, or platform-partnership use cases.
  </Card>
</CardGroup>

## Scope and access model

Forex Masters uses a tenant-aware institutional model. Organizations are represented as colleges or companies, with separate administrator, member, and invitation records. Every integration is scoped to the institution approved during onboarding.

<Steps>
  <Step title="API Gateway & Authentication">
    The Institutional system connects to the API gateway and authenticates the integration.
  </Step>

  <Step title="Scope & Platform Services">
    The connection determines organization and role scopes to access Forex Masters platform services.
  </Step>

  <Step title="Data & Events">
    Authorized data (organization data, learner records) is accessed, and lifecycle events are delivered via webhooks.
  </Step>
</Steps>

An integration can access only the data and operations granted to its organization and credentials. Forex Masters does not provide an unrestricted database interface or organization-wide access to personal trader data.

<Warning>
  Institutional API access does not grant authority to place trades, manage client funds, access broker credentials, or make trading decisions on behalf of learners or employees.
</Warning>

## Available integration capabilities

Exact resources, fields, rate limits, and authentication requirements are defined in your organization’s implementation agreement and API credentials package.

| Capability | Typical use | Availability |
| - | - | - |
| Enterprise Analytics | Retrieve real-time seat counts, active users, completion rates, study hours, and department leaderboards | Enterprise Admin scope |
| Organization profile | Confirm tenant identity and integration status | Approved integrations |
| Membership management | Create, invite, deactivate, or reconcile approved members | Scope-dependent |
| Cohort and enrollment sync | Align internal cohorts with Forex Masters programs | Scope-dependent |
| Learning progress | Retrieve authorized completion and engagement signals | Scope-dependent |
| Completion records | Reconcile course completion and certificate workflows | Scope-dependent |
| Webhooks | Receive approved membership and learning lifecycle events | Scope-dependent |
| SSO and identity workflows | Connect an approved identity provider or roster source | Enterprise engagement |

<Note>
  Data fields are purpose-limited. Access to journals, trade records, broker-account information, AI conversations, behavioral profiles, and personal memory is restricted and is not assumed to be available through institutional reporting.
</Note>

## Getting access

Institutional integrations are configured jointly by your technical contact and the Forex Masters implementation team.

<Steps>
  <Step title="Define the use case">
    Identify the system you are connecting, the intended user population, required data flows, and the operational owner for the integration.
  </Step>

  <Step title="Complete architecture and security review">
    Forex Masters reviews identity, tenancy, data-minimization, webhook, retention, and compliance requirements before credentials are issued.
  </Step>

  <Step title="Provision a sandbox or controlled test environment">
    Your team receives implementation-specific credentials, base URLs, permitted scopes, test organization identifiers, and webhook setup guidance.
  </Step>

  <Step title="Validate the integration">
    Test authentication, tenant isolation, idempotency, webhook verification, error handling, and reconciliation workflows before production activation.
  </Step>

  <Step title="Activate production access">
    Production credentials are enabled after technical and operational sign-off.
  </Step>
</Steps>

## Authentication

Institutional integrations use credentials issued to the organization, not credentials belonging to an individual learner or administrator.

Your approved integration package will specify:

* 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.

Never embed institutional secrets in browser code, mobile applications, public repositories, client-side analytics, or support tickets.

<Warning>
  Store credentials only in an approved server-side secret manager. Rotate credentials immediately if they are exposed, suspected to be exposed, or no longer required.
</Warning>

### Request expectations

All requests should include the organization context required by your integration agreement and must be made from a trusted server environment.

```http theme={"system"}
Authorization: Bearer <institutional-access-token>
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
X-Request-ID: <your-correlation-id>
```

The header names and token format above are illustrative. Use the values and protocol supplied with your issued API reference.

## Organization isolation

Forex Masters applies organization-aware authorization at the application boundary and uses scoped data access for authenticated operations. Institutional integrations must preserve this isolation model.

### 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.

<AccordionGroup>
  <Accordion title="Can an institution access all learner trading records?">
    No. Institutional access is purpose- and scope-limited. Trading journals, broker-account data, behavioral signals, AI conversations, and other sensitive user records are not broadly exposed for organization reporting. Any exceptional data requirement requires explicit review, legal basis, and a documented agreement.
  </Accordion>

  <Accordion title="Can the API execute trades or connect directly to broker accounts?">
    No. The Institutional API is not an execution interface and does not provide authority to place orders, manage funds, or operate learner broker accounts.
  </Accordion>

  <Accordion title="Can we use the API from a browser application?">
    No. Use a server-side integration. Browser-delivered credentials cannot be treated as institutional secrets and should never be used for privileged organizational operations.
  </Accordion>

  <Accordion title="Can we sync a whole student roster automatically?">
    Yes, where roster synchronization is included in your approved scope. Implement creates, updates, deactivations, retries, and reconciliation as an auditable server-side workflow.
  </Accordion>
</AccordionGroup>

## Membership lifecycle

Institutional membership should mirror the real-world relationship between your organization and the learner or employee.

A typical integration lifecycle is:

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

Webhooks allow your systems to respond to relevant events without continuously polling for changes. Events are available only when included in your approved integration scope.

Typical event categories may include:

* 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

Your receiver must:

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.

```ts theme={"system"}
// 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 })
}
```

<Note>
  Persist the verified event before performing downstream work. This protects your integration from timeouts, duplicate deliveries, and temporary dependency failures.
</Note>

## Error handling and retries

Build integrations to tolerate transient network and service failures.

| Response class | Meaning | Recommended action |
| - | - | - |
| `2xx` | Request accepted or completed | Record the result and continue. |
| `400` | Invalid request shape or unsupported field | Correct the request; do not retry unchanged. |
| `401` / `403` | Authentication, signature, scope, or tenant authorization failure | Stop retries and review credentials, scope, and organization context. |
| `404` | Resource unavailable within your approved scope | Confirm identifiers and lifecycle state. |
| `409` | Duplicate, conflicting, or state-incompatible operation | Reconcile current state before retrying. |
| `422` | Request is syntactically valid but cannot be processed | Review validation detail and business state. |
| `429` | Rate limit reached | Respect `Retry-After` when supplied; apply exponential backoff. |
| `5xx` | Temporary platform or upstream failure | Retry with bounded exponential backoff and jitter. |

Use idempotency keys for mutation requests. A retry without idempotency protection can create duplicate invitations, inconsistent roster state, or difficult reconciliation work.

## Security and privacy requirements

Institutional integrations operate in a sensitive environment that may include identity data, educational progress, trading education activity, and other personal information. Apply the following controls from the start.

<CardGroup cols={2}>
  <Card title="Data minimization" icon="filter">
    Request, store, and transmit only the data needed for the approved integration purpose.
  </Card>

  <Card title="Least privilege" icon="key">
    Use the smallest scope set possible and separate test, staging, and production credentials.
  </Card>

  <Card title="Auditability" icon="clipboard-list">
    Retain operational logs for requests, outcomes, access changes, and webhook processing without storing unnecessary sensitive payloads.
  </Card>

  <Card title="Secure operations" icon="shield-check">
    Protect secrets, encrypt data in transit and at rest, manage staff access, and maintain an incident-response process.
  </Card>
</CardGroup>

### 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.

<Warning>
  Forex Masters is an education and intelligence platform. Institutional integrations must not present platform content, progress indicators, or AI-generated material as individualized investment advice, guaranteed performance, or execution instructions.
</Warning>

## Implementation checklist

<Steps>
  <Step title="Design tenant-safe data flows">
    Map each inbound and outbound field, identify its owner, establish the minimum retention period, and document the permitted purpose.
  </Step>

  <Step title="Build server-side authentication">
    Store credentials in your secret manager, implement rotation support, and ensure no privileged token reaches a browser.
  </Step>

  <Step title="Implement idempotent membership sync">
    Use stable identifiers, idempotency keys, explicit state transitions, and a reconciliation job for missed events.
  </Step>

  <Step title="Secure webhook processing">
    Verify signatures against raw request bodies, deduplicate deliveries, queue processing, and monitor failures.
  </Step>

  <Step title="Test negative paths">
    Validate unauthorized tenant access, malformed input, duplicate mutations, expired credentials, replayed webhooks, rate limits, and downstream outages.
  </Step>

  <Step title="Complete production review">
    Confirm contacts, incident procedures, data handling, monitoring, and rollback plans with Forex Masters before activation.
  </Step>
</Steps>

## Support and change management

Use your designated Forex Masters business or implementation contact for:

* 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.

Plan integration changes as controlled releases. Changes to scopes, identity mappings, webhook endpoints, data fields, or downstream usage may require renewed technical, security, and compliance review.

<Note>
  Do not rely on undocumented endpoints, internal application routes, database tables, browser traffic, or reverse-engineered requests. Only the interface and credentials explicitly issued to your organization are supported for institutional use.
</Note>

## Related resources

<CardGroup cols={2}>
  <Card title="Enterprise & College Administration" icon="building-2" href="/docs/b2b/team-management">
    Learn how Forex Masters supports institution-level membership and learning operations.
  </Card>

  <Card title="Security & Compliance" icon="shield" href="/docs/support/security-2fa">
    Review the principles governing secure, responsible platform use.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.