Skip to main content

Identity REST API

You can use the Identity API to manage the administrative configuration for your organization that is in the Veracode Platform.

The API provides endpoints for managing users, teams, and business units, using the create, update, read, and delete actions on their respective objects. You can also manage API service accounts, which are also called API users. You can use the API credentials endpoint to get information about API credentials expiration, revoke API credentials, or renew your API credentials.

For some API requests, you must set your updates as incremental or partial. partial=true indicates that you are updating only a subset of properties for an object. incremental=true indicates that you are adding items to a list for an object property, such as adding users to a team.

Permissions and authentication​

Before you can use all endpoints of the Identity REST APIs, you must have one of these accounts with the required role:

  • An API service account with the Admin API role.
  • A user account with the Administrator role.

All other API service account and user account roles can access these endpoints:

  • /users/self
  • /users/api_credentials

This API uses API ID/key credentials and HMAC authentication to provide improved security. Before you can send requests, you must complete these configurations:

Ensure you access the APIs with the domain for your region.

Identity API specification​

The Identity API specification is available from SwaggerHub.

Create a user account​

To create a user account, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/users" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
   "email_address":"[email protected]",
   "first_name":"Example",
   "last_name":"User",
   "ip_restricted":false,
   "pin_required": true,
   "active":true,
   "roles":[
      {
         "role_name":"extseclead"
      },
      {
         "role_name":"extsubmitanyscan"
      }
   ],
   "title":"Sample",
   "user_name":"[email protected]",
   "userType":"VOSP",
   "teams":[
      {
         "team_id":"teamId"
      }
   ]
}

For some roles, you must include one or more of these scan types that the user can submit:

  • extsubmitanyscan: any scan type
  • extsubmitstaticscan: Static Analysis
  • extsubmitdynamicanalysis: Dynamic Analysis
  • extsubmitmanualscan: Manual Penetration Testing

When Veracode creates the user account and configures the authentication, it can take up to one minute.

Roles​

Role short nameRole nameAdditional roles required
deletescansDelete Scansextseclead or extcreator
sandboxadminSandbox Administrator 
sandboxuserSandbox User 
workSpaceAdminWorkspace Administrator 
workSpaceEditorWorkspace Editor 
extsecleadSecurity LeadUsers must have at lease one of these additional roles: extsubmitmanualscan, extsubmitstaticscan, extsubmitdynamicscan, extsubmitdynamicanalysis, extsubmitdynamicmpscan, extsubmitanyscan, extsubmitdiscoveryscan
extcreatorCreatorUsers must have the additional role that matches the type of scan they want to create and submit: extsubmitmanualscan, extsubmitstaticscan, extsubmitdynamicscan, extsubmitdynamicanalysis, extsubmitanyscan, extsubmitdynamicmpscan, extsubmitdiscoveryscan
extsubmitterSubmitterUsers must have the additional role that matches the type of scan they want to submit: extsubmitmanualscan, extsubmitstaticscan, extsubmitdynamicscan, extsubmitdynamicanalysis, extsubmitanyscan, extsubmitdynamicmpscan, extsubmitdiscoveryscan
extreviewerReviewer 
extmitigationapproverMitigation Approver 
extexecutiveExecutive 
securityinsightsonlySecurity Insights 
securityLabsUserSecurity Labs User 
extadminAdministratorContact Veracode Technical Support to assign this role to a user.
extpolicyadminPolicy Administrator 
extelearneLearning 
teamAdminTeam Admin 
greenlightideuserGreenlight IDE User 

Create a SAML user account​

To create a user account with SAML sign-on, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/users" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
   "email_address":"[email protected]",
   "first_name":"Example",
   "last_name":"User",
   "ip_restricted":false,
   "active":true,
   "roles":[
      {
         "role_name":"extseclead"
      },
      {
         "role_name":"extsubmitanyscan"
      }
   ],
   "title":"Sample",
   "saml_user":true,
   "saml_subject":"[email protected]",
   "user_type":"VOSP"
 }

See the list of roles you can assign to users.

Create an API service account​

To create an API service account, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/users" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
   "user_name":"vitunicornidentityapi",
   "first_name":"VITUnicorn",
   "last_name":"IdentityAPI",
   "email_address":"[email protected]",
   "ip_restricted":false,
   "active":true,
   "roles":[
      {
         "role_name":"noteamrestrictionapi"
      },
      {
         "role_name":"apisubmitanyscan"
      },
      {
         "role_name":"uploadapi"
      },
      {
         "role_name":"resultsapi"
      }
   ],
   "permissions":[
      {
         "permission_name":"apiUser"
      }
   ],
   "teams":[
      {
         "team_id":"teamId"
      }
   ]
}

If you want an API service account to have access to all applications, regardless of which team the user is a member, use noteamrestrictionapi.

To restrict scan types for a user with the uploadapi role, use one or more of these additional roles:

  • apisubmitanyscan
  • apisubmitstaticscan
  • apisubmitdynamicscan
  • apisubmitmanualscan

User roles​

Role short nameRole nameAdditional roles required
submitterapiUpload API - Submit OnlyUsers must have the additional role that matches the type of scan they want to submit: apisubmitstaticscan, apisubmitdynamicscan, apisubmitmanualscan, noteamrestrictionapi, apisubmitanyscan
uploadapiUpload and Scan APIUsers must have the additional role that matches the type of scan they want to run: apisubmitstaticscan, apisubmitdynamicscan, apisubmitmanualscan, noteamrestrictionapi, apisubmitanyscan
resultsapiResults API
mitigationapiMitigation API
archerreportsArcher Reports API
greenlightapiuserGreenlight API User
adminapiAdmin API

List all users in an organization​

To list all users in an organization, including user accounts and API service accounts, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users"

By default, the output results show up to 20 users per page. To page through the list, you can resend the request with ?page=1, ?page=2, and so on, appended to the end.

To increase the page size from the maximum of 20 and list more users in the output, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users?page={page number}&size={page size}"

For example, set page=0&size=50 to increase the size of page 0 to 50.

To list only users whose accounts are enabled, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users?enabled=true"

To list only users whose accounts are disabled, set enabled=false.

Search for users​

To search for users, including user accounts and API service accounts, by username, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users?user_name={user_name}"

You must specify the full username. The request does not support matching partial usernames.

To search for users by email address, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users?email_address={email_address},{email_address}"
Important

In each email address, you must specify the @ character using URL encoding or the request fails. For example, user%40domain.com. Use a comma-separated list to specify multiple addresses.

To search for users using with partial terms, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?search_term={search_term}"

You can search for partial strings of the username, first name, last name, or email address. You can combine this call with other search parameters.

To search for users by API ID, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?api_id={api_id}"

You must specify the exact API ID. You can combine this call with other search parameters.

Filter users​

To filter users by role, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?role_id={role_id}"

To filter users by user type, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?user_type={user_type}"

To filter users by login status, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?login_status={login_status}"

To filter users by SAML status, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?saml_user=true"

To filter users by team, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/users/search?team_id={team_guid}"

Update a user​

To update an existing account, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/users/{userId}?partial=true" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
 "ip_restricted": true,
 "allowed_ip_addresses": ["72.22.163.41"]
}

Update a user to require multifactor authentication​

To update an existing account, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/users/{userId}?partial=true" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "pin_required": true
}

Delete a user​

To delete an account, send the following request:

http --auth_type=veracode_hmac DELETE "https://api.veracode.com/api/authn/v2/users/{userId}"

userId is the numeric ID, separated with hyphens, for the target account. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

Generate API credentials for your account​

To generate new API credentials for your account, send the following request:

http --auth-type=veracode_hmac --json POST "https://api.veracode.com/api/authn/v2/api_credentials"

Generate API Credentials for an API user​

To send this request, you must be the administrator for the specified user.

To generate new API credentials for the API user you specify for userId, send the following request:

http --auth-type=veracode_hmac --json POST "https://api.veracode.com/api/authn/v2/api_credentials/user_id/{userId}"

Get API credentials expiration​

Use these requests to view the expiration date for API credentials.

Get the expiration date for your account​

To view the expiration date and time for your API credentials, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/api_credentials"

Get the expiration date by API ID​

To view credentials expiration information for a specific API ID, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/api_credentials/{apiCredsId}"

Get the expiration date for an API user​

To send this request, you must be the administrator for the specified user.

To view the current API credentials and their expiration for the API user you specify for userId, send the following request:

http --auth-type=veracode_hmac --json GET "https://api.veracode.com/api/authn/v2/api_credentials/user_id/{userId}"

You must include the --json parameter to force the request to send the Content-Type: application/json in the HTTP header.

Revoke API credentials​

This use case scenario provides the Identity REST API request for revoking API credentials. The credentials expire immediately after you revoke them. You can no longer use them to access Veracode.

You can use the Veracode Platform or the Identity API to generate new API credentials.

To revoke the API credentials for a specific API ID, send the following request:

http --auth-type=veracode_hmac --json DELETE "https://api.veracode.com/api/authn/v2/api_credentials/{apiCredsId}"

You must include the --json parameter to force the request to send the Content-Type: application/json in the HTTP he

Delete API credentials for an API user​

To delete the API credentials from the API user you specify for userId, send the following request:

http --auth-type=veracode_hmac --json DELETE "https://api.veracode.com/api/authn/v2/api_credentials/user_id/{userId}"

You must include the --json parameter to force the request to send the Content-Type: application/json in the HTTP header.

List all roles in an organization​

To list all roles in an organization, including user accounts and API service accounts, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/roles"

By default, the output results list up to 20 roles per page. To page through the list, append ?page=1, ?page=2, and so on, to the end of your request.

To increase the page size from the maximum of 20 and list more roles in the output, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/roles?size=500"

List roles that include a specific permission​

To list the roles that contain a specific permission, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/roles?size=500&permission_name={permission_name}"

See the full list of permissions.

List all permissions in an organization​

To list all Veracode permissions, including for user accounts and API service accounts, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/permissions?"

By default, the output results show up to 20 permissions per page. To page through the list, resend the request with ?page=1, ?page=2, and so on, appended to the end. For example:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/permissions?page=4"

Get details of a role​

To view information about a specific role, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/roles/{role_id}"

The role details include the name, description, associated permissions, and more.

To get the role_id, list the roles in your organization.

Create a custom role​

To create a custom role, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/roles" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "role_name": "developer",
  "role_description": "Developer",
  "is_api": false,
  "jit_assignable": true,
  "jit_assignable_default": true,
  "permissions": [
    {
      "permission_name": "ManageApiCredentials",
      "permission_types": [
        "retrieve",
        "revoke",
        "generate"
      ]
    },
    {
      "permission_name": "viewResults"
    },
    {
      "permission_name": "viewDynamicAnalysisResult"
    },
    {
      "permission_name": "updateResults"
    },
    {
      "permission_name": "ManageUser",
      "permission_types": [
        "retrieve",
        "update"
      ]
    }
  ]
}

See the list of permissions you can include when creating roles.

Properties​

You use JSON properties to create and update custom roles with the Identity REST API.

Each role must include role_name, role_description, and permissions, as shown in the following example:

{
  "role_name": "developer",
  "role_description": "Developer",
  "permissions": [
    {
      "permission_name": "ManageApiCredentials",
      "permission_types": [
        "retrieve",
        "revoke",
        "generate"
      ]
    },
    {
      "permission_name": "viewResults"
    }
  ]
}

The following table describes the JSON properties for creating and updating custom roles.

PropertyTypeDescription
role_name
Required		StringInternal name of the custom role. Must be lower case and contain no spaces. Veracode automatically prepends custom- to the name. For example, if you enter developer, the internal name is custom-developer.
role_description
Required		StringUser-facing name of the custom role. This name appears in the Veracode Platform when selecting roles for users.
is_apiBooleanWhether the role applies to API service accounts. Default is false.
requires_tokenBooleanWhether users must have multifactor authentication to use the role. Default is false.
team_admin_manageableBooleanWhether Team Admins can manage the role. Default is false.
jit_assignableBooleanWhether you can use the role with Just-In-Time provisioning. Default is false.
jit_assignable_defaultBooleanWhether you can use this role in SAML assertions. Default is false.
permissions
Required		ArrayList of permissions that the role grants to users.
child_rolesArrayList of roles whose permissions this role grants to users.
ignore_team_restrictionsBooleanWhether the role is limited to teams the user is assigned to. Default is false.

Create a custom role using child roles​

When you create a custom role, you can use child roles to grant all the permissions associated with existing roles to your custom role. To include the permissions from a Veracode role or a custom role in your new custom role, include them in the payload when you create the role.

To create a custom role that uses child roles, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/roles" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "role_name": "developer",
  "role_description": "Developer",
  "is_api" : false,
  "jit_assignable" : true,
  "jit_assignable_default" : true,
  "permissions": [
  ],
  "child_roles": [{
    "role_name": "custom-myOtherCustomRole"
  },
    {
      "role_description": "Creator"
    }]
}

See the list of properties and the list of permissions you can include when creating roles.

Update a custom role​

To update a custom role, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/roles/{role_id}?partial=true" < input.json

To get the role_id, list the roles in your organization. You cannot update the standard Veracode roles.

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "role_name": "developer",
  "role_description": "Developer",
  "is_api" : false,
  "jit_assignable" : true,
  "jit_assignable_default" : true,
  "permissions": [
    {
      "permission_name": "ManageApiCredentials",
      "permission_types": [
        "retrieve",
        "revoke",
        "generate"
      ]
    },
    {
      "permission_name": "viewResults"
    },
    {
      "permission_name": "viewDynamicAnalysisResult"
    },
    {
      "permission_name": "updateResults"
    },
    {
      "permission_name": "ManageUser",
      "permission_types": [
        "retrieve",
        "update"
      ]
    }
  ]
}

See the list of properties and the list of permissions you can include when updating roles.

Add permissions to a custom role​

To add permissions to a custom role, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/roles/{role_id}?partial=true&incremental=true" < input.json

To add permissions to the role without redefining the other details of the role, include incremental=true in the request.

To get the role_id, list the roles in your organization. You cannot update the standard Veracode roles.

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
    "permissions": [
         {
            "permission_name": "ManageUser",
            "permission_types": [
                "retrieve",
                "update"
            ]
        },
        {
            "permission_name": "dashboard"
        },
        {
            "permission_name": "exportCustomData"
        },
        {
            "permission_name": "lookerAnalyticsViewer"
        }
    ]
}

See the list of properties and the list of permissions you can include when updating roles.

Delete a custom role​

To delete a custom role from your organization, send the following request:

http --auth-type=veracode_hmac DELETE "https://api.veracode.com/api/authn/v2/roles/{role_id}"

To get the role_id, list the roles in your organization. You cannot delete the standard Veracode roles.

Create a team​

To create a team, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/teams" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "team_name": "Physical Penetration Testing"
}

Add users to a team​

To add users to a team, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/teams/{teamId}?partial=true&incremental=true" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "team_name": "Red Team Testing",
  "users": [
    {
      "user_name": "[email protected]"
    },
    {
      "user_name": "[email protected]"
    }
  ]
}

You can specify user_id or user_name.

Important

You must set incremental=true or the request overwrites the list of users instead of adding them to the specified team.

Get a list of teams​

To view a list of all teams of which you are a member, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/teams"

You can also view information about a specific team.

To view a list of all teams in your organization, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/teams?all_for_org=true"

Get team details​

To view information about a specific team in your organization, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/teams/{teamId}"

teamId is the numeric ID, separated with hyphens, for the target team. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

The request output includes information about any users who are linked to the team.

Update a team​

To change the name of a team, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/teams/{teamId}?partial=true" < input.json

teamId is the numeric ID, separated with hyphens, for the target team. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "team_name": "Physical Penetration Testing"
}

Delete a team​

To delete a team, send the following request:

http --auth-type=veracode_hmac DELETE "https://api.veracode.com/api/authn/v2/teams/{teamId}"

teamId is the numeric ID, separated with hyphens, for the target object. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

Create a business unit​

To create a business unit, send the following request:

http --auth-type=veracode_hmac POST "https://api.veracode.com/api/authn/v2/business_units" < input.json

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "bu_name": "Business Unit Five"
}

Add a team to a business unit​

To add a team to a business unit, send the following request:

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/business_units/{businessUnitId}?partial=true&incremental=true" < input.json

businessUnitId is the numeric ID, separated with hyphens, for the target business unit. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "teams": [
    {
      "team_id": "d56ebdfd-6797-4566-96a1-67455975b6a4"
    }
  ]
}

Get a list of business units​

To list all business units for an organization, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/business_units"

You can also view details about a specific business unit.

Get business unit details​

To view details about a specific business unit, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/api/authn/v2/business_units/{businessUnitId}"

businessUnitId is the numeric ID, separated with hyphens, for the target business unit. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

The output results include information about any teams that are linked to the specified business unit.

You can also list all business units.

Update a business unit​

To update a business unit, send the following request:

Important

You must set partial=true or the request overwrites all existing business units.

http --auth-type=veracode_hmac PUT "https://api.veracode.com/api/authn/v2/business_units/{businessUnitId}?partial=true" < input.json

businessUnitId is the numeric ID, separated with hyphens, for the target business unit. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "bu_name": "My business unit"
}

Delete a business unit​

To delete a business unit, send the following request:

http --auth-type=veracode_hmac DELETE "https://api.veracode.com/api/authn/v2/business_units/{businessUnitId}"

businessUnitId is the numeric ID, separated with hyphens, for the target business unit. For example: 7336556f-9ef2-4a1c-b536-be8608822db6.

Last updated on