# Setting Authentications Permissions Through the API

With Treasure Data’s Policy-Based Permissions you can select which users can import and export data into and out of Treasure Data. While you can set, create, and assign policies to users through TD Console,__ authentications permissions or access control policies must be set through the API. This might include setting full permissions, changing permissions, or assigning authentication permissions.

The API operations differ from the settings found in the Web Console. Where the term View in the UI becomes use when setting authentication permissions through the API.

You might not see the same behavior or payload if your administrator has not enabled granular permissions for Authentication. Contact your Customer Success representative to enable the feature.

In setting authentications, it’s important to have an understanding of the basic terminology.

| **Term** | **Description** |
|  --- | --- |
| **Authentications**
 | Permits Treasure Data to create an authentication to exchange data:
- **use_limited**: adds a restricted set of authentications which include view and use permission to the user.
- **use**: gives users permission for global view and use access to all authentications
- **owner_manage**: gives users permission to create their own authentications as well as view, use, edit, and delete any authentication they created.
- **full**: gives the user permission for global view, edit, use access to all authentications.

 |
| **Source**
 | After you've created a new authentication, you can create a new source specifying what kind of document you will use for the data. This setting enables access permission on sources when authentication is accessible. Accessible authentications depend on the Authentication permission you have.
For instance, if you have Authentications/use_limited, you can access sources created from only specified authentications.
**Note:** In the latest version of Policy Based Permissions, sources:full becomes sources:restricted.
 |
| **Destinations**
 | After you have created an authentication, you can set up queries or activations to export data to a specific location. Use permission on all available destinations relies on your Authentications permission.
**Note:** In the latest version of Policy Based Permissions, destinations:full becomes destinations:restricted.
 |


A user's access to activations depends on the master segment owner's authentication permissions and their own authentication access combined. Learn [how Authentications Permissions Affect Activations in the Audience Studio.](/products/control-panel/security/policies/how-authentications-permissions-affect-activations-in-the-audience-studio)

## Prerequisites

* Knowledge of policy-setting protocols
* ID for existing policy
* Empty policy assigned to a specific user
* API reference for [Policy-Based Permissions](/products/control-panel/security/policies/permission-policy-api)


## Viewing Existing Lists of Policy IDs and Policy Names

With the following command, you can retrieve all the information about existing policies.

1. From the command line, use the GET command to call up the policy API to get the policy name or id.



```http
GET /v3/access_control/policies
```

1. The response includes identifying information about the policy, including id, account_id, policy name, a description of the policy, and the number of users assigned to the specific policy.



```json
[
  {
    "id": 67,
    "account_id": 123,
    "name": "some_policy",
    "description": "written about the policy",
    "user_count": 3
  }
]
```

## Viewing a List of Policy Permissions by Policy ID

With the following command, you can retrieve information about a policy’s permissions.

1. Use the GET command and the `policy_id` to view a list of permissions associated with a policy.



```http
GET /v3/access_control/policies/:policy_id/permissions
```

1. View permissions defined in a specific policy in the response.



```json
{
  "WorkflowProject": [
    {
      "operation": "view"
    }
  ],
  "WorkflowProjectLevel": [
    {
      "operation": "view",
      "name": "my_wf"
    }
  ],
  "Segmentation": [
    {
      "operation": "full"
    }
  ],
           "MasterSegmentConfigs": [
             {
               "operation": "view"
             }
           ],
           "MasterSegmentConfig": [
             {
               "operation": "view",
               "id": "42"
             }
           ],
           "SegmentAllFolders": [
             {
               "operation": "view",
               "audience_id": "42"
             }
           ],
           "SegmentFolder": [
             {
               "operation": "view",
               "id": "42"
             }
           ],
           "Authentications": [
             {
               "operation": "use"
             }
           ],
           "Sources": [
             {
               "operation": "restricted"
             }
           ],
           "Destinations": [
             {
               "operation": "restricted"
             }
  ]
}
```

## Viewing a User’s Existing Policies

With the following command, you can retrieve information about a user’s policies.

1. Use the GET command and `user_id` to view the user's current policy.



```http
GET /v3/access_control/users/:user_id/policies
```

1. View a specific user’s policy permissions in the response.



```json
[
  {
    "id": 62,
    "account_id": 123,
    "name": "some_policy",
    "description": "written about the policy",
    "user_count": 3
  }
]
```

## Assigning Policies to a Specific User

With the following command, you can assign a policy or a group of policies to a specific user.

1. Use the PATCH command and `user_id` to update the user's policy.



```http
PATCH /v3/access_control/users/:user_id/policies
```

1. In the payload, add the new additional policy to the user’s profile.



```json
{
  "policy_ids": [
    "62",
    "67"
  ]
}
```

## Verifying User Policies and Permissions

1. You can verify the correct policies and permissions were added using the GET command with the `user_id`.



```http
GET /v3/access_control/users/:user_id
```

1. View the user’s policy permissions in the response.



```json
{
  "account_id": "123",
  "user_id": "2629",
  "permissions": {
    "Authentications": [
      {
        "operation": "use"
      }
    ],
    "Sources": [
      {
        "operation": "restricted"
      }
    ],
    "Destinations": [
      {
        "operation": "restricted"
      }
    ]
  },
  "policies": [
    {
      "id": "67",
      "account_id": "123",
      "name": "some_policy",
      "description": ""
    }
  ]
}
```

## Setting Authentication Permissions to Full

To set authentication to full permissions, you must call the appropriate API with the correct policy ID.

1. Use the PATCH command and the specific policy_id to set policy permissions.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, set the authentications operations to full.



```json
{
  "Authentications": [
    {
      "operation": "full"
    }
  ]
}
```

## Changing Authentication Permissions to None

You can set authentication permission to none by passing an empty array to authentications to indicate none permissions.

1. Use the PATCH command to change authentication permissions.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, set empty array to authentications.



```json
{
  "Authentications": []
}
```

## Assigning Authentications to View Only with Sources Permissions set to Restricted

You can assign authentication permissions to use and source permissions to restricted. With this permission, users cannot create new authentications but can view authentications lists and create new sources.

1. Use the PATCH command to change or set authentication permissions.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, set authentications operations to view and sources operations to restricted.



```json
{
  "Authentication": [
    {
      "operation": "use"
    }
  ],
  "Sources": [
    {
      "operation": "restricted"
    }
  ]
}
```

## Assigning use_limited permission

With the following command, you can assign a user permission to view and use specified authentications.

1. Use the PATCH command to set authentication permissions for use_limited.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, add the use-permission on the specified authentication.



```json
{
  "Authentications": [
    {
      "operation": "use_limited",
      "ids": "1,2,6,100"
    }
  ]
}
```

## Assigning owner_managed authentication permission

With the following command, you can configure owner_manage permissions on authentications so a user may create authentications themselves and view, edit, delete, and use authentications they created.

1. Use the PATCH to set authentication permissions for owner_managed.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, grant the `owner_manage` permission so the user can create and manage their own authentications.



```json
{
  "Authentications": [
    {
      "operation": "owner_manage"
    }
  ]
}
```

## Assigning No Permissions for Authentications and Sources

You can restrict access for both authentications and sources by removing the variables for these permissions.

1. Use the PATCH command to change authentication permissions.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, remove the variables for authentications and sources and pass an empty array.



```json
{
  "Authentications": [],
  "Sources": []
}
```

## Assigning Authentication to use_limited with Related Source Permissions

You can assign authentications permissions to use_limited to restrict access within specified authentications. With this permission, users can only view the authentications in the specified list. With an additional restricted sources permissions, users can have full permissions with the sources created from the authentications in the list.

1. Use the PATCH command to change authentication permissions.



```http
PATCH /v3/access_control/policies/:policy_id/permissions
```

1. In the payload, set authentications operations to use_limited, add the specific Authentication ids you want, and set the sources operations to restricted.



```json
{
  "Authentications": [
    {
      "operation": "use_limited",
      "ids": "1,2,3"
    }
  ],
  "Sources": [
    {
      "operation": "restricted"
    }
  ]
}
```