OpenAI Integration

Scimify enables SCIM provisioning for OpenAI organizations, allowing you to invite members, manage organization roles, and sync IdP groups through your identity provider.

Overview

This integration (de)provisions users and groups in your OpenAI organization using the OpenAI Administration API. Scimify accepts standard SCIM requests from your IdP and translates them into organization user, invite, and group API calls.

Key behaviors:

User and group provisioning — sync IdP users and groups to your OpenAI organization
Invite-based user create — new users receive an organization invite (they are not created as active members until they accept)
Role management — optional openai_role SCIM attribute maps to OpenAI organization roles
Deprovisioning — removing access deletes the organization member or cancels a pending invite

Prerequisites

An OpenAI organization with organization administration access
An Admin API key with permission to manage organization users, invites, and (if using group SCIM) groups
Your IdP configured for SCIM provisioning (see Okta SCIM Configuration)

For API details, see the OpenAI Administration API overview.

Configuration Steps

1. Generate an OpenAI Admin API Key

Sign in to the OpenAI Platform
Open Organization Admin API keys
Create a new Admin API key
Set permissions based on what you plan to provision:

Use case	Recommended Admin API key permissions
Users only (invite, role update, deprovision)	Restricted key with Organization admin write
Users and groups	Full admin permissions

Note: OpenAI assigns Admin API capabilities via scopes. Today, a restricted key with Organization admin write is sufficient for user SCIM, but group provisioning currently requires full admin permissions on the Admin API key. This may change if OpenAI adjusts how scopes are grouped for group APIs.

Copy the key and store it securely

Admin keys are for organization administration only and cannot be used for standard model or chat API calls.

2. Configure the Integration in Scimify

Navigate to the Integrations page in your Scimify admin console
Create a new OpenAI integration instance
Set an instance display name (for example, Production OpenAI Org) so you can distinguish multiple OpenAI connections
Enter your Admin API Key
Optionally set a Group Description — stored in Scimify for reference only (OpenAI groups only support a name in the API)
Save the configuration and use Test connection to verify API access
Use Refresh users and Refresh groups to confirm the key can list organization users and groups
Enable the integration to generate a SCIM API key for your Idp
Copy the Scimify SCIM endpoint for your IdP

Your OpenAI organization is determined by the Admin API key; no separate organization ID is required in Scimify.

3. Configure Organization Role Management (Optional)

To assign OpenAI organization roles via SCIM, add the openai_role custom attribute to your IdP user profile and map it into the SCIM user payload.

If openai_role is omitted, Scimify assigns the default role reader.

4. Configure IdP SCIM

Follow the Okta SCIM Configuration guide to connect Okta to your Scimify OpenAI instance, then assign users and groups to the SCIM app.

If you use group push, refresh and import groups from OpenAI in your IdP before pushing so Scimify and your IdP have accurate group IDs (see Known limitations below).

How It Works

User Provisioning

When a user is assigned in your IdP:

Scimify checks whether the email already exists as an organization member
If not, Scimify checks for an existing pending invite for that email
If neither exists, Scimify creates a new organization invite with the requested role

The invited user must accept the invite before they appear as an active organization member in OpenAI.

User Updates

Active members — role changes are applied with the organization user update API
Pending invites — OpenAI does not support updating an invite in place; Scimify deletes the pending invite and creates a new invite with the updated role when openai_role changes
Profile fields — name and email are not updated through this integration as OpenAI accounts are personal accounts; role is the supported user update

User Deprovisioning

When a user is unassigned or deactivated in your IdP:

Active members are removed from the organization
Pending invites are deleted

This is a hard remove from the organization (not a soft disable in OpenAI).

Group Provisioning

When groups are pushed from your IdP:

Scimify creates, renames, and deletes OpenAI organization groups to match IdP group lifecycle events
Group membership is synced to match IdP group assignments
Only accepted organization members can be added to groups — pending invites are skipped (see limitations below)

Group names in OpenAI match the IdP group display name.

Custom SCIM Attribute Configuration

To manage OpenAI organization roles from your IdP, configure the following custom attribute.

Attribute: openai_role

Setting	Value
Type	String
External namespace	`urn:ietf:params:scim:schemas:extension:custom:2.0:User`
Attribute name	`openai_role`
Description	OpenAI organization role for the invited or provisioned user
Default	`reader` (if not sent in SCIM)

Valid values:

Value	Description
`reader`	Standard organization reader (default)
`owner`	Organization owner

Scimify accepts openai_role in any of these common SCIM shapes:

Top-level field: openai_role
Extension key: urn:ietf:params:scim:schemas:extension:custom:2.0:User:openai_role
Nested extension object: urn:ietf:params:scim:schemas:extension:custom:2.0:User → { "openai_role": "owner" }

Suggested Okta profile attribute

In Okta, add a user profile attribute for your OpenAI SCIM app:
- Display name: OpenAI organization role
- Variable name: e.g. openaiRole
- Type: string
- External namespace: urn:ietf:params:scim:schemas:extension:custom:2.0:User
- External name: openai_role
Restrict values to reader or owner (for example, using an enumerated profile field or lifecycle rule)
Map the attribute in the Okta → Scimify provisioning profile so it is included on create and update

Mapping guidance

Set a sensible default (typically reader) for standard employees
Use group rules or entitlements to assign owner only where appropriate
Role changes on pending invites trigger a new invite email from OpenAI

Known Limitations and Behavior Notes

Invite-only create — SCIM “create user” sends an organization invite; users are not fully active until they accept
Group push fails for invited users — OpenAI does not allow pending invitees to be added to groups. Group membership sync for those users will fail until they accept the invite; retry the failed group push after acceptance
Duplicate group names — OpenAI allows multiple groups with the same name. Refresh and import groups from OpenAI in your IdP before pushing groups to avoid mismatched or duplicate group mappings
Conservative API rate limits — OpenAI rate limits can be hit during bulk provisioning (for example, full company onboarding). Scimify respects rate limits, backs off, and returns HTTP 429 to your IdP when needed so Okta can pause and retry automatically. If you hit repeated rate limits, use smaller user and group assignment batches
Role-only user updates — only openai_role is synchronized on update; other profile attributes are ignored
No project or group-role APIs — project membership and OpenAI group role endpoints are out of scope
No custom roles - role assignment via openai_role SCIM attribute currently supports the built-in reader and owner roles

If you need custom roles or project provisioning, contact [email protected] and we can work with you to extend the integration.

Troubleshooting

Authentication failed (401)
- Confirm you are using an Admin API key, not a standard API key
- Regenerate the key in OpenAI Platform and update the Scimify integration config
Users refresh works; groups refresh fails or returns no groups
- Group SCIM currently requires full admin permissions on the Admin API key
- After updating key permissions, save the key in Scimify and run Test connection, then Refresh groups
Rate limit / provisioning retries in Okta
- OpenAI returned HTTP 429; wait for Okta’s automatic retry or reduce push batch size
User created but not in groups
- The user may still have a pending invite — group membership requires an accepted organization member
Group push failed for a newly provisioned user
- Retry group push after the user accepts their OpenAI organization invite
Invalid openai_role
- Ensure the value is reader or owner

Additional Resources

Need Help?

If you encounter issues configuring openai_role mappings, Admin API key permissions, or group push, contact [email protected] for assistance.