Access States

Import an application's access

Imports the complete access list for one application. Users, resources and permissions are matched by email and title. Any access not present in the body is removed. An email matching no known user creates one. If any row cannot be resolved, nothing is written and every rejected row is listed in the response. Importing into an application with an active access-syncing integration is permitted; the next scheduled sync will overwrite what the import wrote. Because this call replaces all of an application’s access, send a unique Idempotency-Key header so an accidentally repeated request is rejected rather than re-applied.

PUT

api

applications

{application_id}

access_states

Import an application's access

curl --request PUT \
  --url https://api.accessowl.com/api/v1/applications/{application_id}/access_states \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access": [
    {
      "permissions": [
        "Admin"
      ],
      "resource": "Billing",
      "user_email": "ana@example.com"
    }
  ]
}
'

import requests

url = "https://api.accessowl.com/api/v1/applications/{application_id}/access_states"

payload = { "access": [
        {
            "permissions": ["Admin"],
            "resource": "Billing",
            "user_email": "ana@example.com"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    access: [{permissions: ['Admin'], resource: 'Billing', user_email: 'ana@example.com'}]
  })
};

fetch('https://api.accessowl.com/api/v1/applications/{application_id}/access_states', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.accessowl.com/api/v1/applications/{application_id}/access_states",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'access' => [
        [
                'permissions' => [
                                'Admin'
                ],
                'resource' => 'Billing',
                'user_email' => 'ana@example.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.accessowl.com/api/v1/applications/{application_id}/access_states"

	payload := strings.NewReader("{\n  \"access\": [\n    {\n      \"permissions\": [\n        \"Admin\"\n      ],\n      \"resource\": \"Billing\",\n      \"user_email\": \"ana@example.com\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.accessowl.com/api/v1/applications/{application_id}/access_states")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access\": [\n    {\n      \"permissions\": [\n        \"Admin\"\n      ],\n      \"resource\": \"Billing\",\n      \"user_email\": \"ana@example.com\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.accessowl.com/api/v1/applications/{application_id}/access_states")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access\": [\n    {\n      \"permissions\": [\n        \"Admin\"\n      ],\n      \"resource\": \"Billing\",\n      \"user_email\": \"ana@example.com\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "created": 12,
    "deleted": 5,
    "unchanged": 40,
    "updated": 3
  }
}

{
  "error": "invalid_params",
  "errors": [
    {
      "field": "application_id",
      "messages": [
        "is invalid"
      ]
    }
  ],
  "message": "Invalid request parameters"
}

{
  "error": "Invalid bearer token."
}

{
  "error": "forbidden",
  "message": "Access denied"
}

{
  "error": "not_found",
  "message": "Resource not found"
}

{
  "error": "idempotency_key_already_used",
  "message": "This idempotency key has already been used"
}

{
  "error": "validation_failed",
  "errors": {
    "status": [
      "access request was already granted"
    ]
  },
  "message": "The request contains invalid data"
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 1200 seconds."
}

This is a full replace, not a merge

Import sends the complete access list for one application. Users, resources and permissions are matched by email and title, and any access not present in the body is removed — this is a replace, not an incremental update. An email matching no known user creates one, so send the full intended state every time, not just the rows you want to add or change. The write is all-or-nothing: if any row cannot be resolved, nothing is written and every rejected row is listed in the response. Importing into an application with an active access-syncing integration is allowed, but the next scheduled sync will overwrite whatever the import wrote.

Because this call replaces all of an application’s access, an omission is a deletion. Read back the current state with List access states and build the body from there rather than from a partial list.

Long-running request — combine with idempotency

Replacing every user, resource and permission for an application is a large operation. For a big application the request can be long-running, and the underlying TCP connection may be held open long enough that a proxy, load balancer or client timeout drops it before AccessOwl responds — even though the import is still being applied on the server. A plain retry after such a timeout would re-run the whole replace. To retry safely, send a unique Idempotency-Key header and reuse the same key on every retry of that import — a repeat then returns 409 Conflict instead of re-applying the replace.

See Idempotency for the full contract — key format, how 409/422 responses behave, and retention.

Authorizations

Authorization

string

header

required

Bearer token authentication. Pass your AccessOwl API token in the Authorization header as Bearer <token>.

Headers

Idempotency-Key

string

Optional key (1–255 chars) for safely retrying a request. Reusing the same key for the same request returns 409 Conflict and is not processed again — this confirms the request was already received. Keys are retained for 14 days.

Required string length: 1 - 255

Path Parameters

application_id

string<uuid>

required

Application ID

Body

application/json

Complete access list

The complete access list for one application. Any access not listed is removed.

access

object[]

required

One entry per user and resource

Show child attributes

Response

Import result

Counts of the changes the import made

data

object

required

Show child attributes

Last modified on September 29, 2026

Import an application's access

curl --request PUT \
  --url https://api.accessowl.com/api/v1/applications/{application_id}/access_states \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access": [
    {
      "permissions": [
        "Admin"
      ],
      "resource": "Billing",
      "user_email": "ana@example.com"
    }
  ]
}
'

import requests

url = "https://api.accessowl.com/api/v1/applications/{application_id}/access_states"

payload = { "access": [
        {
            "permissions": ["Admin"],
            "resource": "Billing",
            "user_email": "ana@example.com"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    access: [{permissions: ['Admin'], resource: 'Billing', user_email: 'ana@example.com'}]
  })
};

fetch('https://api.accessowl.com/api/v1/applications/{application_id}/access_states', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.accessowl.com/api/v1/applications/{application_id}/access_states",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'access' => [
        [
                'permissions' => [
                                'Admin'
                ],
                'resource' => 'Billing',
                'user_email' => 'ana@example.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.accessowl.com/api/v1/applications/{application_id}/access_states"

	payload := strings.NewReader("{\n  \"access\": [\n    {\n      \"permissions\": [\n        \"Admin\"\n      ],\n      \"resource\": \"Billing\",\n      \"user_email\": \"ana@example.com\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.accessowl.com/api/v1/applications/{application_id}/access_states")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access\": [\n    {\n      \"permissions\": [\n        \"Admin\"\n      ],\n      \"resource\": \"Billing\",\n      \"user_email\": \"ana@example.com\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.accessowl.com/api/v1/applications/{application_id}/access_states")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access\": [\n    {\n      \"permissions\": [\n        \"Admin\"\n      ],\n      \"resource\": \"Billing\",\n      \"user_email\": \"ana@example.com\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "created": 12,
    "deleted": 5,
    "unchanged": 40,
    "updated": 3
  }
}

{
  "error": "invalid_params",
  "errors": [
    {
      "field": "application_id",
      "messages": [
        "is invalid"
      ]
    }
  ],
  "message": "Invalid request parameters"
}

{
  "error": "Invalid bearer token."
}

{
  "error": "forbidden",
  "message": "Access denied"
}

{
  "error": "not_found",
  "message": "Resource not found"
}

{
  "error": "idempotency_key_already_used",
  "message": "This idempotency key has already been used"
}

{
  "error": "validation_failed",
  "errors": {
    "status": [
      "access request was already granted"
    ]
  },
  "message": "The request contains invalid data"
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 1200 seconds."
}

General

Quickstart for...

Guides

Integrations

Resources

Import an application's access

This is a full replace, not a merge

Long-running request — combine with idempotency

Authorizations

Headers

Path Parameters

Body

Response