Cofense User Management API Guide

Auth method: API Token (Bearer) for PhishMe/PhishMe REST API; OAuth 2.0 Client Credentials for Cofense Vision API

Setup steps

1. Log in to the Cofense PhishMe admin console.
2. Navigate to Settings > API Access and generate an API token (client ID + secret pair).
3. Store the token securely; include it as a Bearer token in the Authorization header for all API requests.
4. For Cofense Vision: POST client credentials to the Vision OAuth token endpoint to obtain a short-lived access token, then pass it as Authorization: Bearer .

Required scopes

List Users

• Method: GET
• URL: https://api.cofense.com/v2/users
• Watch out for: Pagination parameters and exact field names may differ between PhishMe API versions; verify against your tenant's API version.

Request example

GET /v2/users?page=1&per_page=100
Authorization: Bearer <token>

Response example

{
  "users": [
    {"id":"u123","email":"alice@example.com","firstName":"Alice","active":true}
  ],
  "total": 1
}

Get User

• Method: GET
• URL: https://api.cofense.com/v2/users/{id}
• Watch out for: Returns 404 if user ID does not exist or belongs to a different organization.

Request example

GET /v2/users/u123
Authorization: Bearer <token>

Response example

{
  "id": "u123",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Smith",
  "active": true
}

Create User

• Method: POST
• URL: https://api.cofense.com/v2/users
• Watch out for: Duplicate email addresses return a 409 Conflict error.

Request example

POST /v2/users
Authorization: Bearer <token>
Content-Type: application/json

{"email":"bob@example.com","firstName":"Bob","lastName":"Jones"}

Response example

{
  "id": "u456",
  "email": "bob@example.com",
  "firstName": "Bob",
  "active": true
}

Update User

• Method: PUT
• URL: https://api.cofense.com/v2/users/{id}
• Watch out for: Full PUT may require all fields; use PATCH if partial updates are supported in your API version.

Request example

PUT /v2/users/u456
Authorization: Bearer <token>
Content-Type: application/json

{"firstName":"Robert","department":"Engineering"}

Response example

{
  "id": "u456",
  "firstName": "Robert",
  "department": "Engineering"
}

Deactivate User

• Method: PUT
• URL: https://api.cofense.com/v2/users/{id}
• Watch out for: Deactivated users are excluded from future campaigns but historical data is retained.

Request example

PUT /v2/users/u456
Authorization: Bearer <token>
Content-Type: application/json

{"active": false}

Response example

{
  "id": "u456",
  "active": false
}

Delete User

• Method: DELETE
• URL: https://api.cofense.com/v2/users/{id}
• Watch out for: Deletion is permanent and removes all associated training/phishing history for that user.

Request example

DELETE /v2/users/u456
Authorization: Bearer <token>

Response example

HTTP 204 No Content

List Groups

• Method: GET
• URL: https://api.cofense.com/v2/groups
• Watch out for: Groups are used for campaign targeting; ensure group IDs are valid before assigning users.

Request example

GET /v2/groups
Authorization: Bearer <token>

Response example

{
  "groups": [
    {"id":"g1","name":"Engineering","memberCount":42}
  ]
}

SCIM: Provision User

• Method: POST
• URL: https://api.cofense.com/scim/v2/Users
• Watch out for: SCIM endpoint base URL and token are configured separately via the Recipient Sync setup in the PhishMe admin console. Requires Enterprise plan.

Request example

POST /scim/v2/Users
Authorization: Bearer <scim_token>
Content-Type: application/scim+json

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"alice@example.com","name":{"givenName":"Alice","familyName":"Smith"},"active":true}

Response example

{
  "id": "scim-u789",
  "userName": "alice@example.com",
  "active": true,
  "meta": {"resourceType": "User"}
}

• Rate limits: Cofense does not publicly document specific rate limit numbers. Limits are enforced per API token and vary by plan tier. Enterprise customers may negotiate higher limits.
• Rate-limit headers: Unknown
• Retry-After header: Unknown
• Rate-limit notes: Contact Cofense support for rate limit specifics. HTTP 429 is returned when limits are exceeded.
• Pagination method: offset
• Default page size: 100
• Max page size: 1000
• Pagination pointer: page / per_page (PhishMe REST API); startIndex / count (SCIM 2.0)

• Webhooks available: No
• Webhook notes: Cofense PhishMe does not publicly document outbound webhook support for user management events. Event-driven integrations are typically handled via SCIM provisioning or polling the REST API.
• Alternative event strategy: Poll the REST API for user/activity changes, or use SCIM provisioning from your IdP (Okta, Entra ID, OneLogin) to push user lifecycle events into Cofense.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.cofense.com/scim/v2

• Supported operations: Create User (POST /Users), Read User (GET /Users/{id}), Update User (PUT /Users/{id}), Deactivate User (PATCH /Users/{id} active=false), List Users (GET /Users), List Groups (GET /Groups), Update Group Membership (PATCH /Groups/{id})

Limitations:

• Available only on Enterprise plan; not available on lower tiers.
• SCIM token is generated within the Cofense PhishMe admin console under Recipient Sync settings.
• SAML 2.0 SSO is available but not a prerequisite for SCIM provisioning.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), and OneLogin; Google Workspace is not listed as officially supported.
• Exact SCIM base URL may be tenant-specific; confirm in admin console.
• Group push support may be limited depending on IdP connector version.

Three primary automation scenarios are supported by the API.

First, automated onboarding via SCIM: configure Recipient Sync in the PhishMe admin console to generate a bearer token, connect your IdP, map attributes (email, firstName, lastName, department), and new users are provisioned via POST /scim/v2/Users - note the SCIM token does not auto-rotate.

Second, bulk import via REST API: POST individual user records to /v2/users with email, firstName, and lastName; handle 409 Conflict on duplicate emails; there is no documented bulk-create endpoint, so SCIM is preferred for large datasets. Third, offboarding: retrieve the user's Cofense ID via GET /v2/users?

email=... , then send PUT /v2/users/{id} with active: false; prefer deactivation over DELETE, as deletion permanently removes all training and phishing history.

Automated Employee Onboarding via SCIM

1. Configure Cofense Recipient Sync in the PhishMe admin console to generate a SCIM bearer token and note the SCIM base URL.
2. In your IdP (e.g., Okta), add the Cofense PhishMe SCIM application and enter the base URL and bearer token.
3. Map IdP user attributes (email, firstName, lastName, department) to SCIM User schema fields.
4. Enable provisioning; new IdP users assigned to the Cofense app will be automatically created in PhishMe via POST /scim/v2/Users.
5. Verify user appears in PhishMe admin console under Recipients.

Watch out for: SCIM token does not auto-rotate; store securely and rotate manually if compromised. Enterprise plan required.

Bulk User Import via REST API

1. Authenticate by generating an API token in PhishMe Settings > API Access.
2. Prepare a list of users in JSON format with required fields: email, firstName, lastName.
3. Loop through the list and POST each user to https://api.cofense.com/v2/users.
4. Handle 409 Conflict responses for duplicate emails by skipping or updating existing records.
5. Assign users to groups via PUT /v2/users/{id} with the groups array populated.

Watch out for: No official bulk-create endpoint documented; individual POST calls per user may be slow for large datasets. Consider SCIM for large-scale provisioning.

Employee Offboarding – Deactivate User

1. Retrieve the user's Cofense ID by calling GET /v2/users?email=departing@example.com.
2. Send PUT /v2/users/{id} with body {"active": false} to deactivate the account.
3. Confirm the user is excluded from future phishing campaigns by checking active status.
4. If using SCIM/IdP, deprovision the user in the IdP; the SCIM connector will send a PATCH /scim/v2/Users/{id} with active=false automatically.

Watch out for: Avoid DELETE unless permanent removal of training history is intended; deactivation preserves historical reporting data.

Several sharp edges require explicit handling. Cofense has multiple distinct products (PhishMe, Triage, Vision, Intelligence) with different base URLs and auth schemes - confirm which product API is in scope before building. API versioning (v1 vs v2) affects available fields and endpoint paths; always verify against your tenant's supported version.

Rate limits are not publicly disclosed; implement exponential backoff on HTTP 429 responses. Webhooks are not supported for user management events - event-driven workflows must rely on SCIM provisioning from an IdP or polling the REST API.

Google Workspace is not listed as an officially supported IdP for SCIM, and group push support may be limited depending on the IdP connector version.