Poppulo APIs use OAuth 2.0 Client Credentials for authentication. To access an API, create an API key in Integrations Manager, assign the appropriate API roles, and use the generated client credentials to obtain an access token.

API access is controlled through API roles assigned to an API key. Depending on the API, roles may be assigned at both the enterprise and sub-account level.

Prerequisites

To create an API client, you must:

• Have access to Integrations Manager.
• Have permission to create and manage API keys.
• Know which enterprise and/or sub-accounts your integration needs to access.
• Know which APIs your integration requires.
• Understand which API roles are needed.

Create an API Key

1. Sign in to Integrations Manager.
2. Navigate to API Keys.
3. Select Create.
4. Enter the API Details.
   • Name
     • A unique, descriptive name for the integration.
   • Description
     • A short explanation of how the API client will be used.

Example

• Name: User Provisioning
• Description: Automates provisioning of users from Entra ID to Poppulo via SCIM.

These details are for administrative clarity only and do not affect behaviour.

5. Select the accounts your integration needs to access.

6. Assign the required API roles. Enterprise Permissions example Sub-Account permissions example

7. Review your configuration and create the API key.

8. Securely store the generated Client ID and Client Secret.

Important: The Client Secret is displayed only once when the API key is created. Store it securely. If you lose the Client Secret, you must generate a new one. Generating a new Client Secret immediately invalidates the previous secret. If the API key is already being used by an application, you'll need to update that application with the new secret before it can continue requesting access tokens.

Understanding API roles

API roles determine which APIs an integration can access. Roles are assigned at two levels:

• Enterprise roles grant access to enterprise-wide functionality.
• Sub-account roles grant access to APIs for individual accounts.

Many integrations require roles at both levels.

Enterprise API roles

Sub-account API roles

Role dependencies

Some sub-account roles depend on enterprise roles.

The API Content role requires the Enterprise API Account Access role. This enterprise role enables your integration to retrieve enterprise account information, discover available sub-accounts, and identify the target account used by supported APIs.

Without this enterprise role, requests that require account discovery or sub-account selection cannot be completed successfully.

Common role combinations

Obtaining an access token

Use the OAuth 2.0 Client Credentials flow with your Client ID and Client Secret to obtain an access token from the token endpoint.

Token URL

Poppulo provides two geo-specific OAuth endpoints to obtain a valid Access Token. One is for US-hosted customers and the other for EU-hosted customers. Integrations should use the endpoint that corresponds to the region where the Poppulo account is hosted. If you’re unsure which region your account is hosted in, check the URL in your browser when you’re signed in to Poppulo. For example, a URL beginning with admin.eu.poppulo-app.com indicates an EU-hosted account. Alternatively, contact your Poppulo Account Manager for assistance.

• US-hosted customers: https://iam.us2.poppulo-app.com/oauth/v2/oauth-token
• EU-hosted customers: https://iam.eu2.poppulo-app.com/oauth/v2/oauth-token

Example request

POST /oauth/v2/oauth-token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials 
scope=poppulo
client_id=YOUR_CLIENT_ID 
client_secret=YOUR_CLIENT_SECRET

Example response

{ 
  "access_token": "eyJ...", 
  "token_type": "Bearer", 
  "expires_in": 3600 
} 

Calling the API

Authorization: Bearer ACCESS_TOKEN 

Best practices

• Assign only the roles required for your integration.
• Store Client Secrets securely.
• Never embed secrets in client-side applications.
• Rotate Client Secrets regularly. Be aware that generating a new Client Secret immediately invalidates the previous secret. Ensure all applications using the API key are updated with the new secret before rotating to avoid service disruption.
• Request a new access token when the current token expires.
• Create separate API keys for different integrations.
• Review assigned API roles regularly.

Troubleshooting

403 Forbidden

Verify that the API key has the required roles, that they are assigned at the correct level (enterprise or sub-account), and that any required enterprise role dependencies have been assigned.

401 Unauthorized

Check that the access token has not expired, the Client ID and Client Secret are valid, and the Bearer token is included in the Authorization header.