Book a demo
Documentation menu

API keys and public API

Create and revoke OpenAleph API keys, authenticate to the partner API, what the API allows (members, job titles, field options, org units) and where the reference lives.

Who can do thisAdmin

OpenAleph offers a public API, called the partner API, so that your company's systems (usually your HRIS or an integration middleware) can send member data to OpenAleph and read it back. Access is controlled with API keys that admins create in the Company developer area.

Before you start

  • You must be an Admin. Scoped admins and other levels cannot see or use API keys.
  • An API key belongs to your company, not to a person. It keeps working if the admin who created it leaves.

Open the Company developer area

  1. At the bottom of the main menu, click the code icon (tooltip Api Keys), next to Help & Support.
  2. The Company developer page opens (a full page, without the main menu): "Here you can manage your developer settings, including API keys and event reporting functionalities." It has two cards:
    • Go to api keys: "In this section, you can create and manage your API keys to access OpenAleph's APIs."
    • Go to ETL reports: "In this section, you see a list of reported jobs and their statuses." (see Integrations and HR data sync).

Create an API key

  1. Click Go to api keys. The Api keys page lists existing keys with their Name, Public ID and Created at date.
  2. Click Create api key.
  3. Enter an Api key name (required), for example "HRIS sync - production", then click Save.
  4. The message "Api key has been created successfully." appears and the Api key secret is displayed. Copy it (copy icon next to the secret) and store it in a safe place (a password manager or your integration's secret store).
  5. Click Done. The key appears in the list with its Public ID (the first part of the secret).

Important: "This API key will be displayed only once. Please make sure to copy and store it securely, as you won't be able to view it again. If you lose it, you can generate a new API key at any time."

Revoke an API key

  1. On the Api keys page, click the bin icon on the key's row.
  2. Confirm Confirm API Key Deletion: "Deleting this API key will immediately revoke its access. Any integrations or scripts using it will fail until updated. Continue?"
  3. Click Delete. "Api key deleted successfully." confirms it: the key disappears from the list and stops working at once. When no key is left, the page shows "You haven't generated any API keys yet".

To rotate a key without interruption: create a new key, update your integration with it, check that it works, then delete the old key.

Using the API

Authentication

Send the key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

A missing or invalid key returns an error 401 with the hint "Pass your API key in the Authorization header as: Bearer YOUR_API_KEY".

Base URL and versions

  • Current version: https://app.openaleph.io/partners/v2
  • Legacy version (member creation only): https://app.openaleph.io/partners/v1

What the API allows

The partner API covers member data and the lists that describe your organisation. It does not give access to interviews, trainings, goals or other module content.

Endpoint What it does
GET /users_schema Lists the profile fields of your company and their technical identifiers, to know what you can send.
GET /users Lists members (filter by status=active or inactive), with their access level and scoped admin perimeter. Paginated with page[number] and page[size].
POST /users Creates or updates one member.
POST /users/bulk Creates or updates many members in one call.
POST /job_titles/bulk Creates or updates job titles.
POST /fields/{field}/options/bulk Creates or updates the options of a select field (for example work locations).
POST /fields/{field}/nodes/bulk Creates or updates organisation units.

Key rules:

  • Members are identified by their company_uid (your employee ID). Required fields: company_uid, email, firstname, lastname, status, access_level.
  • Each member payload is a full update: send all required fields every time.
  • The manager is set with manager_company_uid. Custom profile fields are sent in extras, using the identifiers from /users_schema.
  • Scoped admins can be sent with their perimeter (perimeter and exclusions), see Scoped admins and perimeters.
  • Sending status: inactive deactivates the member and records a departure date.
  • Bulk endpoints for job titles, options and units accept up to 1,000 entries per call and can safely be called with your full lists every time.
  • Member creation and updates accept an Idempotency-Key header, so a retried request is not applied twice.

Important: Member data sent to the API is not applied immediately. It is queued and processed by the daily synchronisation, and the result appears in the ETL report. The first push also switches your company to synchronised mode, in which members can no longer be added or edited by hand in OpenAleph. Read Integrations and HR data sync before starting.

API reference

The full interactive reference (request and response formats, examples, error codes) is available at https://app.openaleph.io/api-docs. Select API V2 partners in the list.

Common questions

I lost the secret of a key.

It cannot be displayed again. Create a new key, update your integration, then delete the old one.

I don't see the code icon in the menu.

It is only shown to admins.

I pushed a member through the API but I don't see the change.

Changes are applied by the next daily synchronisation. Check the ETL report of that run in Company developer › Go to ETL reports.

Can I use the API to export interview answers or training results?

No. Use the exports available in each module, see Exports and reports.

Still stuck?

Our team answers every question. Tell us what you are trying to do and we'll walk you through it. Contact support