title: API Key Management category: Security tags: api-key, authentication, programmatic, access, tokens priority: Normal
API Key Management
IdentityCenter provides a REST API for programmatic access to identity data, synchronization operations, and administrative functions. API keys authenticate these requests, and managing them properly is essential for security. This article covers creating, using, rotating, and revoking API keys.
Overview
API keys allow external systems, scripts, and integrations to interact with IdentityCenter without requiring interactive user authentication. Each key is:
- Tied to a specific name and description for identification
- Scoped to a set of permissions (read-only, read-write, or admin)
- Optionally set to expire after a defined period
- Tracked for usage monitoring and auditing
The IApiKeyRepository manages all key operations in the data layer, and all key-related actions are recorded in the audit log.
Creating an API Key
Step 1: Navigate to API Key Management
- Go to Administration > API Keys
- Click Create API Key
Step 2: Configure Key Details
| Field | Description | Example |
|---|---|---|
| Name | A descriptive name for the key | "SIEM Integration" |
| Description | What this key is used for | "Read-only key for Splunk to pull audit logs" |
| Scope | Permission level for the key | Read-Only |
| Expiration | When the key should automatically expire | 90 days from creation |
Step 3: Select the Scope
Choose the minimum scope required for the integration:
| Scope | Permissions | Use Cases |
|---|---|---|
| Read-Only | Query objects, read audit logs, pull reports | SIEM integration, monitoring dashboards, reporting tools |
| Read-Write | Everything in Read-Only plus create/update objects, trigger syncs | HR system integration, automated provisioning, helpdesk tools |
| Admin | Full API access including settings, user management, and configuration changes | Infrastructure automation, CI/CD pipelines, management scripts |
Important: Always select the least privileged scope that meets the integration's requirements. A SIEM that only reads audit logs does not need Read-Write or Admin access.
Step 4: Copy and Secure the Key
After creation, the full API key is displayed exactly once. Copy it immediately and store it securely:
- Store in a secrets manager (Azure Key Vault, HashiCorp Vault, AWS Secrets Manager)
- Never store API keys in source code, configuration files committed to version control, or plain-text documents
- Never share keys via email or chat
If you lose the key, you must generate a new one. IdentityCenter stores only a hashed version after initial display.
Using API Keys in Requests
Include the API key in the Authorization header of every API request:
Authorization: ApiKey your-api-key-here
Example: List Users
GET /api/v1/objects?type=user HTTP/1.1
Host: identitycenter.example.com
Authorization: ApiKey ic_key_a1b2c3d4e5f6g7h8i9j0...
Accept: application/json
Example: Get Audit Logs
GET /api/v1/audit?startDate=2026-01-01&endDate=2026-02-20 HTTP/1.1
Host: identitycenter.example.com
Authorization: ApiKey ic_key_a1b2c3d4e5f6g7h8i9j0...
Accept: application/json
Example: Trigger a Sync
POST /api/v1/sync/projects/{projectId}/execute HTTP/1.1
Host: identitycenter.example.com
Authorization: ApiKey ic_key_a1b2c3d4e5f6g7h8i9j0...
Content-Type: application/json
Note: All API requests must be made over HTTPS. Requests over plain HTTP are rejected.
API Key Rotation
Regular key rotation limits the blast radius if a key is compromised. Follow this process:
Rotation Steps
- Create a new key with the same scope and a name that indicates it is the replacement (e.g., "SIEM Integration - Feb 2026")
- Update the integration to use the new key
- Verify the integration works with the new key by monitoring API requests
- Revoke the old key once you have confirmed the new key is working
- Update documentation to reflect the new key name and creation date
Recommended Rotation Schedule
| Key Scope | Rotation Frequency | Rationale |
|---|---|---|
| Admin | Every 30 days | Highest privilege, highest risk |
| Read-Write | Every 60 days | Can modify data |
| Read-Only | Every 90 days | Lower risk, but still rotate regularly |
Monitoring API Key Usage
Track how each key is being used to detect anomalies:
- Navigate to Administration > API Keys
- Each key shows usage statistics:
| Metric | Description |
|---|---|
| Last Used | Timestamp of the most recent API request with this key |
| Request Count | Total number of requests made with this key |
| Last IP Address | The IP address of the most recent request |
| Created Date | When the key was created |
| Expires | When the key will automatically expire |
What to Watch For
- A key that was never used may indicate a forgotten integration or an unnecessary key that should be revoked
- A key showing requests from unexpected IP addresses may indicate compromise
- A Read-Only key making an unusual volume of requests may indicate data exfiltration
- A key used after business hours when the integration should be idle warrants investigation
Revoking API Keys
Revoke a key immediately if you suspect compromise:
- Navigate to Administration > API Keys
- Find the key to revoke
- Click Revoke
- Confirm the revocation
Revocation is immediate. Any subsequent API requests using the revoked key receive a 401 Unauthorized response. Revocation is logged in the audit trail.
When to Revoke
- The key may have been exposed (committed to a public repository, sent in email, logged in plain text)
- The integration that used the key has been decommissioned
- An employee who had access to the key has left the organization
- The key has expired and a replacement is in use
- Unusual activity is detected on the key
API Key Audit Trail
All key management actions are recorded in the audit log:
| Event | Details Captured |
|---|---|
| Key Created | Key name, scope, expiration, created by |
| Key Used | Endpoint accessed, source IP, timestamp |
| Key Revoked | Key name, revoked by, reason |
| Key Expired | Key name, expiration timestamp |
| Authentication Failed | Key identifier (partial), source IP, endpoint |
Review these events in Administration > Audit or pull them via the API for SIEM integration.
Best Practices
- Use the minimum scope required — A reporting tool needs Read-Only, not Admin
- Set expiration dates on every key — Keys without expiration are a ticking time bomb
- Rotate keys on a schedule — Do not wait for a security incident to rotate
- Use one key per integration — If an integration is compromised, you revoke only that key without affecting others
- Never embed keys in source code — Use environment variables, secrets managers, or configuration providers
- Monitor usage regularly — Review the API Keys page at least monthly for anomalies
- Revoke unused keys — If a key has not been used in 30+ days, confirm it is still needed or revoke it
- Document every key — Use descriptive names and descriptions so any administrator can understand what each key is for
- Enable audit log alerts — Configure notifications for key creation, revocation, and authentication failures
Next Steps
- Audit Logging & Change Tracking — Monitor all API and system activity
- Identity Providers & SSO — Configure user authentication
- API Reference — Full API endpoint documentation
- Security Hardening Guide — Protect your deployment