Skip to content

Getting started with the API

This page walks you through the steps to generate API credentials and make your first API call. By the end of this page, you will have a working connection between your automation tool and Permission Assist.

Step 1: Generate an API token

API tokens authenticate your automation tools when they call the Permission Assist API. Tokens are system-wide — a valid token grants access to all API endpoints.

To generate an API token, complete the following steps:

  1. Log in to Permission Assist as an administrator.
  2. Go to System Configuration > General Settings.
  3. Select the API Keys tab.
  4. Select the Create Token button (+).
  5. In the Name field, enter a descriptive name for this token (for example, "OpCon Nightly Import" or "HRIS Integration").
  6. (Optional) In the Expiration Date field, enter the date when this token should stop working. If you leave this field blank, the token does not expire.

  7. Select the Create button.

    Permission Assist displays the token secret. Copy it now — you will not be able to see it again.

Warning

Store your API token securely. Anyone with access to your token can trigger imports or create Personnel Events. Treat tokens with the same care as a password.

Step 2: Make your first API call

The simplest way to verify that your API connection works is to make a test call from the command line using curl or from a tool like Postman.

The following example stages an import using the API-Triggered Import endpoint:

curl -X POST https://[your-pa-server]/api/application-imports/stage \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your-token]" \
  -d '{
    "applicationId": "[your-application-id]"
  }'

$headers = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Bearer [your-token]"
}

$body = @{
    applicationId = "[your-application-id]"
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "https://[your-pa-server]/api/application-imports/stage" `
    -Method POST `
    -Headers $headers `
    -Body $body

If the request succeeds, Permission Assist returns an HTTP 201 response with a JSON body containing the import details:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "kind": "Application Import",
  "number": 42,
  "type": "Scheduled",
  "status": "Pending",
  "createdBy": "HRIS Integration",
  "buildStart": null,
  "buildEnd": null,
  "log": null,
  "files": [],
  "metrics": null,
  "application": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "kind": "Application",
    "name": "Jack Henry Silverlake",
    "priority": "Critical",
    "isArchived": false,
    "lastUpdated": "2026-02-20T08:15:00"
  }
}

A 201 response means Permission Assist accepted the request and queued the import for processing. The import runs asynchronously in the background.

If you receive an error, refer to Error codes for troubleshooting guidance.

Next steps

Now that you have a working API connection, choose what to do next: