Skip to main content

Background APIs

Some Permit.io API operations take too long to finish within one HTTP request, so they run as background tasks. This page is for developers who call these endpoints: it shows how to start a background task, get its result, wait for it to finish, and handle a failed task. The examples use the Copy Environment endpoint.

Background task endpoints​

OperationStart the taskGet the task result
Copy an environmentPOST /v2/projects/{proj_id}/envs/{env_id}/copy/asyncGET /v2/projects/{proj_id}/envs/{env_id}/copy/async/{task_id}/result

For the request body of each endpoint, see the Environments section of the API reference.

Prerequisites​

Start a background task​

Send the request to the /async endpoint. This example copies the staging environment of the default project into a new environment with the key prod. Replace API_SECRET_KEY with your API key.

curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy/async' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "target_env": {
    "new": {
        "key": "prod",
        "name": "production"
    }
  }
}'
# Response: 202 Accepted

The API returns 202 Accepted, which means Permit accepted the task and is running it in the background. The response body holds the task status and a task_id:

{
  "task_id": "adf8f4e3-5e01-4140-b512-142533007edd",
  "status": "processing",
  "result": null,
  "error": null
}

Get the task result​

Call the result endpoint with the task_id from the start response:

curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy/async/{task_id}/result' \
  -H 'authorization: Bearer API_SECRET_KEY'

While the task runs, status is processing. When the task finishes, status is success and result holds the created object. For Copy Environment, result is the new environment:

{
  "task_id": "string",
  "status": "success",
  "result": {
    "key": "prod",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "avp_policy_store_id": "",
    "name": "production",
    "description": "",
    "custom_branch_name": "",
    "jwks": {},
    "settings": {}
  }
}

The task status field has one of these values:

StatusMeaning
processingThe task is still running. Check again later.
successThe task finished. result holds the result.
failureThe task failed. error holds the error details.
cancelledThe task was cancelled.

Wait for a background task to finish​

Add the wait query parameter to hold the request open until the task finishes. wait is the maximum number of seconds to wait. The API responds as soon as the task finishes, or when wait seconds pass, whichever comes first. The default, wait=0, returns the current status immediately.

Both the start request and the result request accept wait:

curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy/async?wait=60' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "target_env": {
    "new": {
        "key": "prod",
        "name": "production"
    }
  }
}'

If the response still shows processing when the wait ends, call the result endpoint again. For a large environment, poll the result endpoint every few seconds instead of holding one long request open.

Handle a failed background task​

When a background task fails, the result endpoint still returns HTTP 200 OK. Check the status field in the body, not the HTTP status code. For a failed task, result is null and error holds the error code, a title, and a message:

{
  "task_id": "adf8f4e3-5e01-4140-b512-142533007edd",
  "status": "failure",
  "result": null,
  "error": {
    "id": "adf8f4e3-5e01-4140-b512-142533007edd",
    "error_code": "NOT_FOUND",
    "title": "We could not find the requested object/s",
    "message": "The requested data could not be found, we could not find 'Environment' with the given filters. Please try again with different filters.\nIf you are sure there is an object with the given filters, contact our support on Slack for further guidance.",
    "support_link": "https://io.permit.io/slack"
  }
}

In this example, the source environment does not exist. Fix the cause named in error.message, then start a new task. If you can't resolve the error, ask in the Permit Slack community.

Contents

Edit this page

Need help?