---
title: "Import an application's access"
method: PUT
path: "/api/v1/applications/{application_id}/access_states"
tags: ["access_states"]
---

# Import an application's access

`PUT /api/v1/applications/{application_id}/access_states`

## Request

- Base URL: `https://app.accessowl.io`
- URL: `https://app.accessowl.io/api/v1/applications/{application_id}/access_states`
- Auth: HTTP bearer

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.

## Path parameters

- `application_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- ImportAccessStates: The complete access list for one application. Any access not listed is removed.
  - `access` object[], required: One entry per user and resource
    - `permissions` string[], required: Permission titles held on the resource
    - `resource` string, nullable: Resource title. May be omitted for an application with a single resource.
    - `user_email` string, required: Email of the user

## Response `200`

Import result

- AccessImportResult: Counts of the changes the import made
  - `data` object, required
    - `created` integer, required
    - `deleted` integer, required
    - `unchanged` integer, required
    - `updated` integer, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `422`: Validation error
- `429`: Too many requests

## Changes

- **2026-10-31** `5a1f071e40d8`: 2 breaking, 4 warning, 3 info
  - response property `errors/additionalProperties/items/` list-of-types was widened by adding types `object` to media type `application/json` of response `422`
  - removed the required property `message` from the response with the `401` status
  - removed the optional property `errors` from the response with the `401` status
  - removed the optional property `errors` from the response with the `403` status
  - …5 more
- **2026-09-30** `56ece6c3256d`: 1 breaking, 1 info
  - the `access/items/permissions` request property's minItems was increased to `1`
  - the request property `access/items/resource` became nullable
- **2026-09-26** `48cd2eacdde8`: 1 info
  - api operation id `AccessOwlApi.AccessStateController.replace` removed and replaced with `AccessOwlApi.AccessStateController.import`
- **2026-09-22** `1dba1160cea4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/accessowl/apis/accessowl-api/changes/api/v1/applications/:application_id/access_states/put.md)

---

[API](https://skmtc.dev/accessowl/apis/accessowl-api.md) - [All operations](https://skmtc.dev/accessowl/apis/accessowl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/accessowl/apis/accessowl-api/revisions/ff38c63d8807?raw)