Okta Partners

API reference

API Reference

Welcome to the Okta Partners platform API reference. Once your app is approved and a tenant installs it, this API lets your app read and write Okta data — strictly within the scopes that tenant explicitly granted.

The runtime API is hosted by **okta-web** (the core platform app); every request hits the `/apps` path under the base URL. The partner platform (okta-partners) is where you register your app, pick scopes, and manage versions and webhooks.

The API is REST over HTTPS, exchanges JSON (UTF-8), and uses standard HTTP status codes. Every read and write is isolated per tenant and protected by a named scope.

Your first call

curl https://getokta.io/api/apps/whoami \
  -H "Authorization: Bearer $OKTA_PARTNER_TOKEN" \
  -H "Accept: application/json"

Base URL

The runtime API is hosted by okta-web under the following path:

https://getokta.io/api/apps

Sandbox environment:

https://dev.getokta.io/api/apps

Authentication

Every request authenticates with a per-installation **Bearer token**. The token is issued automatically when a tenant installs your app; it is bound to a (tenant, app) pair and carries the granted scopes.

Authorization: Bearer <installation_token>
  • Never embed the token in front-end code or a public repo — store it as a server-side secret (e.g. `OKTA_PARTNER_TOKEN`).
  • The token is rotatable from the partner dashboard; external apps receive the new token over the bridge without a redeploy.
  • A missing or invalid token returns `401 Unauthorized`. A valid token lacking the required scope returns `403 Forbidden`.

Verify your token

curl https://getokta.io/api/apps/whoami \
  -H "Authorization: Bearer $OKTA_PARTNER_TOKEN"
# → { "tenant_id": 42, "module": "your-app", "scopes": [ ... ] }

Scopes

Every piece of data is protected by a scope shaped `..`. Partners get exactly two actions: `read` and `write`. Delete is never granted to partners. You pick scopes when creating the app; the tenant approves them on install.

Scope Description
education.students.read Read students
education.students.write Create / update students
education.guardians.read Read guardians
education.subjects.read Read subjects
education.grades.read Read grades
education.sections.read Read sections
education.academic_years.read Read academic years
education.terms.read Read terms
employees.directory.read Read employee directory
reports.builder.read Report catalog / run, list the school’s letterheads and print on them
reports.builder.write Propose an app-authored letterhead (arrives as a draft)
notifications.providers.send Send via a notification provider
realtime.messages.write Publish an instant message to your app's surfaces (listening needs no scope)

Endpoints

All paths are relative to the base URL above. Write endpoints (POST/PATCH) require the matching scope.

Identity

GET /whoami no scope Current installation info (tenant, app, scopes).
GET https://getokta.io/api/apps/whoami

Current installation info (tenant, app, scopes).

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: none
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_a43d
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Students

GET /education/students education.students.read List students (paginated).
GET https://getokta.io/api/apps/education/students

List students (paginated).

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.students.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_b079
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

GET /education/students/{id} education.students.read A single student.
GET https://getokta.io/api/apps/education/students/{id}

A single student.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.students.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_5905
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id integer required

The resource id in Okta.

POST /education/students education.students.write Create a student.
POST https://getokta.io/api/apps/education/students

Create a student.

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.students.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_0ec3
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

full_name string required

Student's full name.

national_id string

National / residency id.

birth_date date

Birth date (YYYY-MM-DD).

gender enum

male or female.

grade_id integer

Grade id.

section_id integer

Section id.

guardian_id integer

Guardian id.

PATCH /education/students/{id} education.students.write Update a student.
PATCH https://getokta.io/api/apps/education/students/{id}

Update a student.

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.students.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_e45a
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id integer required

The resource id in Okta.

Body Params

full_name string

Student's full name.

national_id string

National / residency id.

birth_date date

Birth date (YYYY-MM-DD).

gender enum

male or female.

grade_id integer

Grade id.

section_id integer

Section id.

guardian_id integer

Guardian id.

Guardians

GET /education/guardians education.guardians.read List guardians.
GET https://getokta.io/api/apps/education/guardians

List guardians.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.guardians.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_aac5
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

GET /education/guardians/{id} education.guardians.read A single guardian.
GET https://getokta.io/api/apps/education/guardians/{id}

A single guardian.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.guardians.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_4be0
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id integer required

The resource id in Okta.

POST /education/guardians education.guardians.write Create a guardian.
POST https://getokta.io/api/apps/education/guardians

Create a guardian.

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.guardians.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_8da4
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

full_name string required

Guardian's full name.

phone string required

Phone in E.164 format.

email string

Email address.

relation enum

father | mother | other.

PATCH /education/guardians/{id} education.guardians.write Update a guardian.
PATCH https://getokta.io/api/apps/education/guardians/{id}

Update a guardian.

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.guardians.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_4ca6
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id integer required

The resource id in Okta.

Body Params

full_name string

Guardian's full name.

phone string

Phone in E.164 format.

email string

Email address.

relation enum

father | mother | other.

Curriculum

GET /education/subjects education.subjects.read Subjects.
GET https://getokta.io/api/apps/education/subjects

Subjects.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.subjects.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_bd8c
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

POST /education/subjects education.subjects.write Create a subject (idempotent).
POST https://getokta.io/api/apps/education/subjects

Create a subject (idempotent).

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.subjects.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_96e0
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

name string required

Subject name.

code string

Subject code.

GET /education/grades education.grades.read Grades.
GET https://getokta.io/api/apps/education/grades

Grades.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.grades.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_7d9a
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

GET /education/sections education.sections.read Sections.
GET https://getokta.io/api/apps/education/sections

Sections.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.sections.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_1d44
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

GET /education/academic-years education.academic_years.read Academic years.
GET https://getokta.io/api/apps/education/academic-years

Academic years.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.academic_years.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_faa5
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

GET /education/terms education.terms.read Terms.
GET https://getokta.io/api/apps/education/terms

Terms.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: education.terms.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_df6c
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

Employees

GET /employees/directory employees.directory.read Employee directory.
GET https://getokta.io/api/apps/employees/directory

Employee directory.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: employees.directory.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_c6a4
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Query Params

page integer

Page number (1-based).

per_page integer

Items per page (max 100).

search string

Optional free-text search.

GET /employees/directory/{id} employees.directory.read A single employee.
GET https://getokta.io/api/apps/employees/directory/{id}

A single employee.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: employees.directory.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_5c8f
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id integer required

The resource id in Okta.

POST /employees/directory employees.directory.write Add an employee (idempotent).
POST https://getokta.io/api/apps/employees/directory

Add an employee (idempotent).

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: employees.directory.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_0fe2
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

full_name string required

Employee's full name.

job_title string

Job title.

email string

Email address.

Reports

GET /reports/builder reports.builder.read Catalog of available reports.
GET https://getokta.io/api/apps/reports/builder

Catalog of available reports.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_5f23
    A stable identifier for this endpoint — quote it to support to speed up tracing.
POST /reports/builder/{key}/run reports.builder.read Run a report (idempotent).
POST https://getokta.io/api/apps/reports/builder/{key}/run

Run a report (idempotent).

  • Rate Limit: HEAVY
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_8dd1
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

key string required

Report key from the catalog.

Body Params

parameters object

Report parameters (report-specific).

GET /reports/templates reports.builder.read The school’s approved letterheads.
GET https://getokta.io/api/apps/reports/templates

The school’s approved letterheads.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_865a
    A stable identifier for this endpoint — quote it to support to speed up tracing.
POST /reports/templates/{id}/render reports.builder.read Print your content on a letterhead — returns a PDF.
POST https://getokta.io/api/apps/reports/templates/{id}/render

Print your content on a letterhead — returns a PDF.

  • Rate Limit: HEAVY
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.read
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_2c93
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id string required

The opaque template id exactly as the listing returned it — not a number.

Body Params

blocks array required

The document body — blocks: heading, text, table, info-row, divider, spacer, image. An unknown type is refused, not skipped.

variables object

Values for the template’s declared variables. An undeclared key is dropped; platform variables cannot be overwritten.

POST /reports/templates reports.builder.write Propose a template (arrives as a draft, idempotent).
POST https://getokta.io/api/apps/reports/templates

Propose a template (arrives as a draft, idempotent).

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_2d4e
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

name_ar string required

Template name in Arabic.

name_en string

Template name in English.

description string

A description shown to whoever picks the template.

type enum

administrative | general.

orientation enum

portrait | landscape.

paper_size enum

a4 | a3 | letter.

header_enabled boolean

Show the header band.

footer_enabled boolean

Show the footer band.

header_right_content string

Right header slot — text accepting {{variables}}.

header_center_content string

Center header slot.

header_left_content string

Left header slot.

footer_right_content string

Right footer slot.

footer_center_content string

Center footer slot.

footer_left_content string

Left footer slot.

watermark_text string

Watermark text.

watermark_opacity integer

Watermark opacity (0–100).

margin_top_mm integer

Top margin in mm (0–40).

margin_right_mm integer

Right margin in mm (0–40).

margin_bottom_mm integer

Bottom margin in mm (0–40).

margin_left_mm integer

Left margin in mm (0–40).

signatures_enabled boolean

Print the signature block at the foot.

signatures_columns integer

Signature block columns (1–4).

signatures_title string

Signature block title.

signatures array

Signatories: title_ar (required), title_en, name, show_line. An empty array removes them all; omitting the key leaves them alone.

variables array

Template fields: key (required), label_ar (required), label_en, type (text|date|number|currency), required, default_value. A key shadowing a platform variable is dropped silently.

PATCH /reports/templates/{id} reports.builder.write Edit a template your app authored (revokes approval).
PATCH https://getokta.io/api/apps/reports/templates/{id}

Edit a template your app authored (revokes approval).

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_1937
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id string required

The opaque template id exactly as the listing returned it — not a number.

Body Params

name_ar string

Template name in Arabic.

name_en string

Template name in English.

description string

A description shown to whoever picks the template.

type enum

administrative | general.

orientation enum

portrait | landscape.

paper_size enum

a4 | a3 | letter.

header_enabled boolean

Show the header band.

footer_enabled boolean

Show the footer band.

header_right_content string

Right header slot — text accepting {{variables}}.

header_center_content string

Center header slot.

header_left_content string

Left header slot.

footer_right_content string

Right footer slot.

footer_center_content string

Center footer slot.

footer_left_content string

Left footer slot.

watermark_text string

Watermark text.

watermark_opacity integer

Watermark opacity (0–100).

margin_top_mm integer

Top margin in mm (0–40).

margin_right_mm integer

Right margin in mm (0–40).

margin_bottom_mm integer

Bottom margin in mm (0–40).

margin_left_mm integer

Left margin in mm (0–40).

signatures_enabled boolean

Print the signature block at the foot.

signatures_columns integer

Signature block columns (1–4).

signatures_title string

Signature block title.

signatures array

Signatories: title_ar (required), title_en, name, show_line. An empty array removes them all; omitting the key leaves them alone.

variables array

Template fields: key (required), label_ar (required), label_en, type (text|date|number|currency), required, default_value. A key shadowing a platform variable is dropped silently.

DELETE /reports/templates/{id} reports.builder.write Delete a draft your app authored.
DELETE https://getokta.io/api/apps/reports/templates/{id}

Delete a draft your app authored.

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: reports.builder.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_43ce
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Path Params

id string required

The opaque template id exactly as the listing returned it — not a number.

Notifications

GET /notifications/capabilities notifications.providers.send Notification channel capabilities.
GET https://getokta.io/api/apps/notifications/capabilities

Notification channel capabilities.

  • Rate Limit: LIGHT
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: notifications.providers.send
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_f406
    A stable identifier for this endpoint — quote it to support to speed up tracing.
POST /notifications/send notifications.providers.send Send a message (idempotent).
POST https://getokta.io/api/apps/notifications/send

Send a message (idempotent).

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: notifications.providers.send
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_3458
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

recipient string required

Recipient (phone or user id).

message string required

Message body.

channel string

Specific channel (optional).

Realtime

POST /realtime/publish realtime.messages.write Push an instant message to your app's own surfaces in this tenant (not idempotent).
POST https://getokta.io/api/apps/realtime/publish

Pushes a message to your app's channel in this tenant only. Listening needs no scope — the installation is the permission, and there is no `realtime.messages.read`.

  • Rate Limit: MODERATE
    How heavily this call counts against your quota: LIGHT < MODERATE < HEAVY.
  • Permission needed: realtime.messages.write
    The scope the tenant must grant your app before this call is allowed.
  • Reference Code: srv_c59d
    A stable identifier for this endpoint — quote it to support to speed up tracing.

Body Params

event string required

Your own event name — `^[a-z][a-z0-9_.:-]{0,63}$`. It never becomes the broadcast event name: that is the fixed `app.message`, and yours travels inside the payload.

data object required

The message payload, at most 8192 bytes of JSON. Anything needing data is read by the surface from the API with its usual scope.

The full, always-current list lives in the auto-generated OpenAPI 3.1 spec: /docs/openapi.json · /docs/postman_collection.json

Pagination

List endpoints are paginated. Use `?page=2&per_page=50` (max 100 per page).

{
  "data": [ ... ],
  "total": 1242,
  "per_page": 20,
  "current_page": 1,
  "last_page": 63
}

Idempotency

Write operations (POST/PATCH) accept an optional header. The same key within 24 hours replays the same stored response — so if your side times out, retrying will not create a duplicate record.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Errors

Errors are returned as a consistent JSON envelope with the appropriate HTTP status code.

{
  "message": "The given scope is not granted for this installation.",
  "error": "scope_not_granted",
  "scope": "education.students.write"
}
Status Name Description
400 Bad Request Malformed or missing request body.
401 Unauthorized Missing or invalid token.
403 Forbidden Valid token, but the required scope is not granted.
404 Not Found Resource not found within the tenant scope.
409 Conflict Idempotency conflict or inconsistent state.
422 Unprocessable Entity Field validation failed.
429 Too Many Requests Rate limit exceeded.
5xx Server Error Transient error — retry with backoff.

Rate limits

Every response carries headers telling you the remaining budget. On exceed, you get `429` with `Retry-After` (seconds). Honor exponential backoff on retry.

Header Description
X-RateLimit-Limit Ceiling for the window.
X-RateLimit-Remaining Remaining in the current window.
Retry-After Seconds until a new request is allowed (with 429).

Webhooks

External apps receive platform events via signed webhooks. Each webhook is an HTTP POST with a JSON body, signed with HMAC-SHA256 over the envelope `.`.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "education.students.created",
  "tenant_id": 42,
  "created_at": "2026-04-26T10:30:15+03:00",
  "data": { "student": { "id": 123, "full_name": "..." } }
}
Header Description
X-Okta-Event Event name.
X-Okta-Delivery-Id UUID stable across retries (for dedup).
X-Okta-Timestamp Unix timestamp at signing.
X-Okta-Signature HMAC-SHA256 signature (hex).

Verify the signature

$expected = hash_hmac(
    'sha256',
    $request->header('X-Okta-Timestamp').'.'.$request->getContent(),
    $YOUR_WEBHOOK_SECRET,
);

if (! hash_equals($expected, $request->header('X-Okta-Signature'))) {
    return response('invalid signature', 401);
}
  • Check `X-Okta-Timestamp` is within the last 5 minutes, and store `X-Okta-Delivery-Id` for at least 15 minutes to reject replays.
  • Respond 2xx within 10 seconds. For long work, accept with 202 immediately and process asynchronously.
  • Retry backoff: 30s → 2m → 10m → 1h → 6h, after which the delivery is marked failed and surfaces on the Webhook Deliveries page in the partner dashboard.

More resources

This reference is a practical summary. For the full picture (integration types, app lifecycle, the manifest, the policy scanner) see the developer guide.