POST Permissions/Object/{guid}/(ptype)/{principal}

Adds a new permissions entry for a principal that does not currently have permissions assigned to the Object. The principal identity can originate from an AD, LDAP, or local identity provider.

Requirements

  • Permissions:  The caller must have Manage permission to the Object. The caller must also be logged in to the same identity provider as the principal specified. For example, if the principal is a group that uses ActiveDirectory1 identity provider, the caller must also be an account that is accessible via ActiveDirectory1.
  • Token scope:  Security:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters

Name

Description

Object

In the request URL, specify the word Object.

{guid}

In the request URL, specify the GUID of the object to assign new permissions.

Depending on your environment, the GUID may be expressed with or without curly braces {}. For example, {3d6b61d-1c71-4603-883f-25b8c2ceecdd}.

(ptype)

In the request URL, use the appropriate syntax for the identity provider type:

  • AD/[providerName]: Active Directory identity provider. For example: /AD/venqa.

  • LDAP/[providerName]: Light Directory Access Protocol. For example: /LDAP/ODSEE.
  • localTrust Protection Platform identity provider.

{principal}

In the request URL, specify a Universal Unique Identifier (UUID) of a person or group. Otherwise, specify the Prefixed Universal. To get this information, call POST Identity/Browse.

(permissions)

Case sensitive. In the request body, specify one or more Effective Permissions parameters to grant the principal access to the object.

Returns

Returns no other content except unless there is an error.

Response description

Name

Description

HTTP 201

Created. Successful new permissions assignment for the specified object and principal.

HTTP 409

The principal already has permissions to the specified object. Error

Error

Permission already exists. Accompanies a HTTP 409.

Example 1: All Permissions Explicitly Specified

Request for example 1

POST https://test.venafi.example/vedsdk/Permissions/object/
{3415e47d-835c-4949-af5b-c226817f7d40}/local/{a58437d1-e6d4-46f8-b790-bc1bedb943f1} 
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "IsAssociateAllowed":false,
   "IsCreateAllowed":false,
   "IsDeleteAllowed":false,
   "IsManagePermissionsAllowed":false,
   "IsPolicyWriteAllowed":false,
   "IsPrivateKeyReadAllowed":true,
   "IsPrivateKeyWriteAllowed":true,
   "IsReadAllowed":true,
   "IsRenameAllowed":false,
   "IsRevokeAllowed":false,
   "IsViewAllowed":true,
   "IsWriteAllowed":true
}

Response for Example 1

HTTP/1.1 201 Created      
{}

Example 2: Subset of Permissions Explicitly Specified

In this example, the API call grants the principal only a limited set of permissions. If the request omits permissions, it is equivalent to setting them to false.

Request for example 2

POST https://test.venafi.example/vedsdk/Permissions/object/{3415e47d-835c-4949-af5b-c226817f7d40}/local/{a58437d1-e6d4-46f8-b790-bc1bedb943f1} 
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "IsPrivateKeyReadAllowed":true,
   "IsPrivateKeyWriteAllowed":true,
   "IsReadAllowed":true,
   "IsViewAllowed":true,
   "IsWriteAllowed":true
}

Response for Example 2

HTTP/1.1 201 Created
         
{}

Example 3: Subset of Permissions Explicitly Specified for AD Principal

In this example, the API call grants read and write permissions to a principal in Active Directory.

Request for example 3

POST https://test.venafi.example/vedsdk/Permissions/object/{3415e47d-835c-4949-af5b-c226817f7d40}/AD/AD1/7f3d301604d7184e98b91b1a8f44b26f 
Authorization:Bearer 4MyGeneratedBearerTknz==      
{
   "IsPrivateKeyReadAllowed":true, 
   "IsPrivateKeyWriteAllowed":true, 
   "IsReadAllowed":true, 
   "IsViewAllowed":true, 
   "IsWriteAllowed":true, 
}         

Response for Example 3

HTTP/1.1 201 Created
         
{}

Example 4: Principal is Already Assigned Permissions on Object

In this example, the principal already has permissions to the specified object.

Request for example 4

POST https://test.venafi.example/vedsdk/Permissions/object/{3415e47d-835c-4949-af5b-c226817f7d40}/local/{a58437d1-e6d4-46f8-b790-bc1bedb943f1} 
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "IsAssociateAllowed":false, 
   "IsCreateAllowed":false, 
   "IsDeleteAllowed":false, 
   "IsManagePermissionsAllowed":false, 
   "IsPolicyWriteAllowed":false, 
   "IsPrivateKeyReadAllowed":true, 
   "IsPrivateKeyWriteAllowed":true, 
   "IsReadAllowed":true, 
   "IsRenameAllowed":false, 
   "IsRevokeAllowed":false, 
   "IsViewAllowed":true, 
   "IsWriteAllowed":true, 
}         

Response for Example 4

HTTP/1.1 409 Conflict
         
{"Error":"Permission already exists."}