Skip to main content
Version: 2.0.0

Background APIs (EAP)

Early Access Program

Background APIs are part of the Early Access Program (EAP) and are subject to change.

Some APIs in Permit run in the background and can be triggered without awaiting a response. These APIs are commonly used for operations that require scheduling, are not time-sensitive, or may take significant time to complete.

Let's look at the Copy Environment API to explain how background APIs should be used - 

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

When triggering Copy Environment, the API will return a 202 Accepted response, indicating that the job has been accepted and is being processed in the background.

The response contains information about the task, including the task_id, which can be used to check its status.

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

After some time, you can check the status of the task using the task_id.

curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy/async/{task_id}/result' \
  -H 'authorization: Bearer API_SECRET_KEY'
{
  "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": {}
  }
}

Waiting for Background tasks​

You can also wait for the background task to be completed by using the wait query parameter.

The wait parameter specifies the maximum time to wait for the task to complete in seconds. By default, wait=0 will return immediately with the current status of the task. The API responds with the task result as soon as it is completed.

You can provide the wait parameter to the initial request or the result status check request.

curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy/async?wait=60` \
  -H 'authorization: Bearer API_SECRET_KEY'

Background tasks may take a long time, up to 30 minutes, so you may want to check the status every couple of seconds.

Error Handling​

When a background task fails, the API will still return a 200 OK response, but the status will be failed, and the error message will be included in the response.

{
  "task_id": "adf8f4e3-5e01-4140-b512-142533007edd",
  "status": "failed",
  "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://permit-io.slack.com/ssb/redirec"
  }
}

Contents