Skip to main content
Version: 2.0.0

Asynchronous APIs

Some API operations can take a while to complete. For these APIs, Permit will run them in the background after the request is complete. When an asynchronous API is called, you will receive a 202 Accepted response, with a unique task_id in response body. You can use this ID to check the status of the task, and to retrieve a result when the task is completed successfully, or an error if the task failed.

Some operations offer both an asynchronous and a synchronous call, for backwards compatibility. The default behavior is to use the synchronous call, but you can request an asynchronous call by setting the ?async=true URL parameter.

Calling an asynchronous API​

The Copy Environment API is an example of an asynchronous-optional API. To call this API, you can use the following curl command:

$ curl -v "https://api.permit.io/v2/projects/{project_id}/envs/{environment_id}/copy" \
 -d '
 {
   "target_env": {
     "name": "Copied Env",
      "key": "copied"
    }
 }'
> POST /v2/projects/{project_id}/envs/{environment_id}/copy HTTP/1.1
>
{
  "target_env": {
        "name": "Copied Env",
        "key": "copied"
  }
}
< HTTP/1.1 200 OK
<
{
  "key": "copied",
  "id": "{copied_environment_id}",
  "organization_id": "{organization_id",
  "project_id": "{project_id}",
  "created_at": "2023-07-30T15:56:21+00:00",
  "updated_at": "2023-07-30T15:56:21+00:00",
  "name": "Copied Env",
  "description": null,
  "jwks": null,
  "settings": null
}

To call the same API asynchronously, you can use the following curl command:

$ curl -v "https://api.permit.io/v2/projects/{project_id}/envs/{environment_id}/copy?async=true" \
 -d '
 {
   "target_env": {
     "name": "Copied Env",
      "key": "copied"
    }
 }'
> POST /v2/projects/{project_id}/envs/{environment_id}/copy HTTP/1.1
>
{
  "target_env": {
    "name": "Copied Env",
    "key": "copied"
  }
}
< HTTP/1.1 202 Accepted
< Content-Type: application/json
< Location: /v2/tasks/copy_environment/{task_id}
<
{
  "operation_name": "copy_environment",
  "task_id": "{task_id}"
}

Checking the status of a task​

To check the status of a task, you can use the following curl command:

$ curl -v "https://api.permit.io/v2/tasks/copy_environment/{task_id}"
> GET /v2/tasks/{task_id} HTTP/1.1
>
< HTTP/1.1 200 OK
< Content-Type: application/json
{
    "id": "{task_id}",
    "operation_name": "copy_environment",
    "status": "finished",
    "created_at": "2024-05-05T18:06:09+00:00",
    "started_at": "2024-05-05T18:06:09+00:00",
    "finished_at": "2024-05-05T18:06:09+00:00",
    "organization_id": "{organization_id}"
}

To retrieve the result of the task, or its error, use the /result endpoint:

$ curl -v "https://api.permit.io/v2/tasks/copy_environment/{task_id}/result"
> GET /v2/tasks/{task_id} HTTP/1.1
>
< HTTP/1.1 200 OK
< Content-Type: application/json
{
  "key": "copied",
  "id": "{copied_environment_id}",
  "organization_id": "{organization_id",
  "project_id": "{project_id}",
  "created_at": "2023-07-30T15:56:21+00:00",
  "updated_at": "2023-07-30T15:56:21+00:00",
  "name": "Copied Env",
  "description": null,
  "jwks": null,
  "settings": null
}

Contents