POST Teams

Creates a team and assigns Venafi products and Policy folders as assets. When you create a team, a Policy folder automatically appears with the same name.

A team:

  • Resides in the local identity provider. However, members, which are Trust Protection Platform users or groups, can originate from a local, AD, or LDAP provider.
  • Includes at least one owner and one or more identity members.
  • Can view the product assignments, assets, and other information.

    View team members and owners in the UI

Requirements

  • Permissions
    • The caller must have Master Admin permission. However, results are limited to the identity provider that authenticated the caller. For example, if a LDAP caller tries to change information about an AD identity, the API call returns an empty JSON result.
    • In the UI, the permissions are valid for the team you are creating. For more information, see Setting team policies and permissions.
  • Token scope:  Configuration: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

When adding query parameters, use the /? syntax. If you are not passing any parameters, make sure the URL ends with a trailing slash. Otherwise, some environments, such as cURL and PowerShell, return a HTTP 307 Temporary Redirect message.

Input parameters

Name

Description

Assets

(Optional) An array of existing Policy folders that this team already owns and manages. The assets cannot be owned by another group. A Policy folder can only be managed by one group.

Description (Optional) The purpose of the identity team.
Name

A PrefixedName for the new local team. For example, PrefixedName:local:Apache Team3.

Owners

An array of owner identities who automatically add as members. The Identity tree shows that the user has Allow Team Creation but not Master Admin permission. At least one valid identity is required.

The syntax varies based on the identity provider. For more information, see Identity Information:

  • AD: Specify a value for PrefixedName or PrefixedUniversal.
  • LDAP: Specify a value for PrefixedName or PrefixedUniversal.
  • Local: Specify values for both a PrefixedName and PrefixedUniversal.

Members

An array of user or group identities to add to the team. At least one valid identity is required. To get this information, call POST Identity/Browse or look in the UI. Members and owners of a team can see and manage their own Assets.

The syntax varies based on the identity provider. For more information, see Identity Information:

  • AD: Specify a value for PrefixedName or PrefixedUniversal.
  • LDAP: Specify a value for PrefixedName or PrefixedUniversal.
  • Local: Specify values for both a PrefixedName and PrefixedUniversal.
Products

An array of Venafi product names: TLS, SSH, Code Signing.

Returns

TIP  The next step depends on your company's process for Teams:

  • HTTP 307:  If the method is missing a slash (/) at the end of the URL or between the query parameters, this message appears: There is no operation listening for [Web SDK method], but there is an operation listening for [Web SDK method/], so you are being redirected there.
  • HTTP 200: The following message body:
Response description

Name

Description

ID

  • FullName:The Distinguished Name (DN) of the identity group.
  • IsGroup: The value is true if this instance is a group, otherwise false.
  • Name: The group name.
  • Prefix: The AD, LDAP or Identity provider. For more information, see Identity Information.
  • PrefixedName: The concatenated Prefix: and Group Name.
  • PrefixedUniversal: The concatenated Prefix: and Universal.
  • Type: The type of identity:
    • 1: User
    • 2: SecurityGroups
    • 8: DistributionGroups

      -OR-

    • [Combo value]. Any combination of identity types that are related to the Filter. For example: SecurityGroupsandDistributionGroups = 10.
  • Universal: The Universal Unique ID (UUID) that identifies a user or group identity. The formatting including curly braces depends on the settings from the identity provider. For example, Universal: {f32b5c37-c2d7-49aa-9ef4-2d38954a8b9b}.

Invalid Owners

Appears only if an individual or group is not currently a team owner:

  • Prefix: The identity provider prefix that manages the account or group Name. For more information, see Identity Information.
  • PrefixedName: The concatenated Prefix: and account Name. For more information, see Identity Information.
  • PrefixedUniversal: The concatenated Prefix: and Universal. For more information, see Identity Information.

InvalidMembers

Appears only if an individual or group is missing from the identity tree.

  • Prefix: The identity provider prefix that manages the account or group Name. For more information, see Identity Information.
  • PrefixedName: The concatenated Prefix: and account Name. For more information, see Identity Information.
  • PrefixedUniversal: The concatenated Prefix: and Universal. For more information, see Identity Information.
Message

If the response is a HTTP 400, it only contains Message and the reason for failure. Omits all other return values.

  • [Identity Error]
  • [Product] is not a valid product, only [TeamProducts.AcceptedValues] values are allowed.
  • Either the Owners list is empty or all of its identities are invalid.
  • Failed to add owners.
  • Failed to add team assets: [Identity Error]
  • Failed to add team description: [Identity Error]
  • Failed to add team owners: [Identity Error]
  • Failed to add team products: [Identity Error]
  • Failed to start Work To Do for team management. Try later
  • Only Master Admin can create a team.
  • The asset [Asset DN] is already owned by a team existent.Name].
  • The prefixed name of a team identity is missing.

Example: Create a local team and add existing users

Request for Example

POST https://tpp.venafi.example/vedsdk/Teams/
Authorization:Bearer 4MyGeneratedBearerTknz{
   "Owners":[
      {
         "PrefixedName":"local:Admin1",
         "PrefixedUniversal":"local:{e24175e7-b5c9-4dcc-8f3d-45f44eacb1a4}"
      }
   ],
   "Name":{
      "PrefixedName":"local:Apache Team"
   },
   "Members":[
      {
         "PrefixedName":"local:Invalid",
         "PrefixedUniversal":"local:{00000000-0000-0000-0000-000000000000 }"
      },
      {
         "PrefixedName":"local:Approver1",
         "PrefixedUniversal":"local:{956094d5-d8a3-41d0-a212-df9bd092b494}"
      },
      {
         "PrefixedName":"local:Master1",
         "PrefixedUniversal":"local:{a39c183f-c7cb-45a0-8150-fd1df2e245ca}"
      }
   ],
   "Assets":[
      "\\VED\\Policy\\AgentTesting",
      "\\VED\\Policy\\AgentDiscovery"
   ],
   "Products":[
      "CodeSigning",
      "SSH"
   ],
   "Description":"Manage Certificates for CS and SSH"
}

Response for Example

HTTP/1.1 200 OK
{
   "ID":{
      "FullName":"\\VED\\Identity\\Apache Team3",
      "IsGroup":true,
      "Name":"Apache Team3",
      "Prefix":"local",
      "PrefixedName":"local:Apache Team3",
      "PrefixedUniversal":"local:{a2a40a29-3fa4-4568-a837-fe50b79ddfbc}",
      "Type":2,
      "Universal":"{a2a40a29-3fa4-4568-a837-fe50b79ddfbc}"
   },
   "InvalidMembers":[
      {
         "Prefix":"local",
         "PrefixedName":"local:",
         "PrefixedUniversal":"local:{00000000-0000-0000-0000-000000000000 }",
         "Universal":"{00000000-0000-0000-0000-000000000000 }"
      }
   ]
}