---
title: "Add data release permissions"
method: POST
path: "/datacatalog/api/data-release/{id}/permissions"
tags: ["Data Release"]
---

# Add data release permissions

`POST /datacatalog/api/data-release/{id}/permissions`

## Request

- Base URL: `https://data.usgs.gov` (the document declares no server; this is the origin it was published from)
- URL: `https://data.usgs.gov/datacatalog/api/data-release/{id}/permissions`
- Auth: OAuth 2
  - Authorization code: `https://auth.globus.org/v2/oauth2/authorize?scope=openid`
  - Token URL: `https://data.usgs.gov/datacatalog/api/auth/login`

Grant one or more users read or write access to a data release.

Each permission assignment maps a Globus username to a `read` or `write`
permission. The corresponding Globus identities are resolved from the
username and added as members of the release's permission groups:

- **read**  → members are added to the release's read-only (R) group,
  granting the ability to view the release and its files.
- **write** → members are added to the release's read-write (RW) group,
  granting the ability to view and modify the release and its files.

Members are added with the `manager` role so they may in turn manage
group membership.

The request body accepts either a single permission object or a list of
them, so multiple users and permission levels can be granted in one call:

.. code-block::

    [
        {"globus_username": "user1@example.org", "permission": "read"},
        {"globus_username": "user2@example.org", "permission": "write"}
    ]

The caller must have an existing role on the release; otherwise a `403
Forbidden` is returned.

Note: this endpoint operates on the release's Globus groups directly. It
is intended for releases that have not yet been published, as publishing
removes the release's permission groups.

Globus applies each membership change independently, so a partial failure
is possible. The response ``data`` contains the release's ``permissions``
after the update and an ``errors`` list describing any add actions Globus
rejected (with the affected username, permission, and reason). If any
action failed, ``success`` is ``false``.

:param id: The ID of the data release to grant permissions on.
:param data: A single permission assignment or a list of assignments,
    each pairing a Globus username with a `read` or `write` permission.
:param token: A valid bearer token for the user making the request.
:raises ForbiddenException: If the caller has no role on the release.
:raises NotFoundException: If no data release exists for the given ID.
:return: The updated membership and any per-identity failures reported by
    Globus.

## Path parameters

- `id` string, required

## Request body

- union
  - DataReleasePermission: Schema for adding or deleting permission for a data release.
    - `globus_username` string, required: The Globus username receiving the permission.
    - `permission` 'read' | 'write', required
  - DataReleasePermission[]
    - `globus_username` string, required: The Globus username receiving the permission.
    - `permission` 'read' | 'write', required

## Response `200`

Successful Response

- UpdateReleasePermissionsResponse
  - `success` boolean, required: A boolean (true/false) indicating if the request was successful.
  - `message` union, required: Descriptive text providing context or further information about the request.
    - 'Created' | 'A component with componentName "{componentName}" already exists in this data release. Please provide a unique componentName.' | 'Deleted' | 'Deletion error' | 'Unable to delete component.' | 'Data release contains components. All components must be deleted before the data release can be deleted.' | 'DOI assigned to Data Release' | 'An entity_id is missing for some or all creators or contributors. Please add any missing entity_id values and try again.' | 'The useForPreview value may only be set to True for .png or .jpg files.' | 'The Globus Search query was not valid. See https://docs.globus.org/api/search/reference/post_query/ for query syntax.' | 'Globus transfer request successfully submitted' | 'A transfer with identical paths has not yet completed. The current transfer may be terminated in the Globus console or contact ask-sdm@usgs.gov for assistance.' | 'Invalid scopes found for transfer. Please re-authenticated and retry transfer.' | 'A transfer path cannot include a directory.' | 'Duplicate filenames not allowed for transfer.' | 'The source endpoint for the Globus transfer was unavailable. Please confirm source Globus collection is available and try again.' | 'A file name cannot contain any of the following characters: < > : " / \ | ? *. On Microsoft Windows, file paths must be formatted like /C/Users/username/filename.csv.' | 'On Microsoft Windows, file paths must be formatted like /C/Users/username/filename.csv.' | 'An unknown error occurred during the transfer. Please try again later or contact ask-sdm@usgs.gov for assistance' | 'This task cannot be found. Please check the task ID.' | 'Internal server error' | 'Invalid schema' | 'File limit reached in collection.' | 'Metadata file not selected. Select a metadata file before performing index files.' | 'Metadata file not found. Please verify metadata file exists in the collection.' | 'Not authenticated' | 'Not Authorized' | 'Item not found' | 'Permissions updated' | 'Some permission changes could not be applied. See the errors in the response for details.' | 'Request processed successfully' | 'Delete not allowed for published releases' | 'Search not avaiable for data releases with more than 10000 components.' | 'Unable to update status at this time. Contact ask-sdm@usgs.gov for assistance.' | 'Updated' | 'User provided groups must grant manager permission to Horizon identity.' | 'User provided groups must not grant admin permission to the Horizon identity.'
    - string
  - `data` DataReleasePermissionsResult, required: Result of a data release permissions update. Contains the release's membership after the update along with any per-identity failures reported by Globus for the requested add or remove actions.
    - `permissions` DataReleasePermission[]: The active read and write members of the release after the update.
      - `globus_username` string, required: The Globus username receiving the permission.
      - `permission` 'read' | 'write', required
    - `errors` DataReleasePermissionError[]: Add or remove actions that Globus failed to apply.
      - `globus_username` string, nullable: The Globus username the failed action applied to, if it could be resolved.
      - `permission` 'read' | 'write'
      - `identity_id` string, nullable: The Globus identity ID the failed action applied to.
      - `code` string, nullable: The error code returned by Globus for the failed action.
      - `detail` string, nullable: A human-readable description of why the action failed.

## Other responses

- `404`: Not found
- `422`: Validation Error

---

[API](https://skmtc.dev/usgs/apis/usgs-science-data-catalog-api-documentation.md) - [All operations](https://skmtc.dev/usgs/apis/usgs-science-data-catalog-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/usgs/apis/usgs-science-data-catalog-api-documentation/revisions/f5f6a07ba13f?raw)