Teradata User Management API Guide

Auth method: Bearer token (JWT) obtained via Teradata Identity Service; OAuth 2.0 client credentials flow is used for service accounts in VantageCloud Lake.

Setup steps

1. Log in to the VantageCloud Lake console as an Organization Admin.
2. Navigate to Settings > API Access and create a service account client ID and client secret.
3. POST to the Teradata Identity Service token endpoint with client_id, client_secret, and grant_type=client_credentials to obtain a JWT access token.
4. Include the token as 'Authorization: Bearer ' in all subsequent API requests.
5. For on-prem Teradata Database, user management is performed via SQL DDL (CREATE USER, MODIFY USER, DROP USER) over a JDBC/ODBC connection authenticated with database credentials; no REST token flow applies.

Required scopes

List Users

• Method: GET
• URL: https://<env>.teradata.com/api/v1/users
• Watch out for: Endpoint path and exact response schema are based on VantageCloud Lake REST API; on-prem Teradata uses SQL DBC views (DBC.UsersV) instead.

Request example

GET /api/v1/users
Authorization: Bearer <token>
Accept: application/json

Response example

{
  "users": [
    {"userId":"abc-123","username":"jdoe","email":"jdoe@example.com","status":"ACTIVE"}
  ]
}

Get User

• Method: GET
• URL: https://<env>.teradata.com/api/v1/users/{userId}
• Watch out for: userId is the internal UUID, not the database username.

Request example

GET /api/v1/users/abc-123
Authorization: Bearer <token>

Response example

{
  "userId": "abc-123",
  "username": "jdoe",
  "email": "jdoe@example.com",
  "roles": ["DataUser"],
  "status": "ACTIVE"
}

Create User

• Method: POST
• URL: https://<env>.teradata.com/api/v1/users
• Watch out for: For on-prem Teradata, user creation is done via SQL: CREATE USER jdoe AS PASSWORD=xxx, PERM=1e9; No REST equivalent exists.

Request example

POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{"username":"jdoe","email":"jdoe@example.com","roles":["DataUser"]}

Response example

{
  "userId": "abc-123",
  "username": "jdoe",
  "status": "ACTIVE"
}

Update User

• Method: PATCH
• URL: https://<env>.teradata.com/api/v1/users/{userId}
• Watch out for: Username cannot be changed via REST; use SQL RENAME USER on-prem.

Request example

PATCH /api/v1/users/abc-123
Authorization: Bearer <token>
Content-Type: application/json

{"status":"INACTIVE","roles":["OrgAdmin"]}

Response example

{
  "userId": "abc-123",
  "status": "INACTIVE",
  "roles": ["OrgAdmin"]
}

Delete User

• Method: DELETE
• URL: https://<env>.teradata.com/api/v1/users/{userId}
• Watch out for: Deleting a user who owns database objects will fail unless objects are reassigned or dropped first (applies to both REST and SQL DROP USER).

Request example

DELETE /api/v1/users/abc-123
Authorization: Bearer <token>

Response example

HTTP 204 No Content

Assign Role to User (SQL – on-prem/VantageCore)

• Method: POST
• URL: Not documented
• Watch out for: Role grants via SQL require the executing user to hold WITH GRANT OPTION on the role.

Request example

-- SQL DDL
GRANT role_name TO username;

Response example

-- No result set; success indicated by absence of error.

List Roles

• Method: GET
• URL: https://<env>.teradata.com/api/v1/roles
• Watch out for: Role definitions differ between VantageCloud Lake (console roles) and on-prem database roles; they are not interchangeable.

Request example

GET /api/v1/roles
Authorization: Bearer <token>

Response example

{
  "roles": [
    {"roleId":"r-001","name":"OrgAdmin"},
    {"roleId":"r-002","name":"DataUser"}
  ]
}

Get Token (Auth)

• Method: POST
• URL: https://<identity-service>.teradata.com/oauth2/token
• Watch out for: The exact identity service hostname is environment-specific and provided in the VantageCloud Lake console under API Access settings.

Request example

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<id>&client_secret=<secret>

Response example

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

• Rate limits: Teradata's public documentation does not explicitly publish REST API rate limits for VantageCloud Lake management APIs as of the policy date.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No rate limit headers or Retry-After behavior documented in official sources. Contact Teradata support for environment-specific limits.

• Pagination method: offset

• Default page size: 0

• Max page size: 0

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: Teradata VantageCloud Lake and on-prem Teradata Database do not expose documented webhook or event-subscription mechanisms for user management events as of the policy date.

• Alternative event strategy: Poll the /api/v1/users endpoint or query DBC.LogonOff / DBC.EventLog system views on-prem for audit and change detection.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Teradata does not publish a native SCIM 2.0 endpoint for VantageCloud Lake or on-prem Teradata Database.
• IdP-driven provisioning (Okta, Entra ID) is not documented as supported via SCIM connectors.
• User provisioning from an IdP must be handled via the REST management API or SQL DDL with custom integration scripts.

Teradata user lifecycle automation spans two planes: the VantageCloud console and the database engine.

Provisioning a new analyst usually requires both steps:

• Create the console user through the REST management API.
• Create the database user through SQL.
• Grant the required database role or object privileges.

Deprovisioning also needs both layers handled explicitly:

• Disable or remove console access through the management API.
• Block or delete the database user through SQL.
• Terminate active database sessions separately if immediate cut-off matters.

For audits, join console user inventory with database system-view output on a shared username key.

Provision a new analyst in VantageCloud Lake

1. Obtain a Bearer token via POST to the identity service token endpoint using client_credentials.
2. POST /api/v1/users with {username, email, roles:["DataUser"]} to create the console user.
3. Separately, connect to the Teradata database via JDBC and execute: CREATE USER AS PASSWORD=, PERM=5e9, DEFAULT DATABASE=;
4. Execute GRANT TO ; to assign database-level permissions.
5. Verify by GET /api/v1/users/{userId} and by querying SELECT * FROM DBC.UsersV WHERE UserName='';

Watch out for: Console user creation and database user creation are independent steps; omitting either leaves the user unable to access one of the two planes.

Deactivate a departing employee

1. Obtain a Bearer token.
2. PATCH /api/v1/users/{userId} with {"status":"INACTIVE"} to disable console access.
3. Connect to the database and execute: MODIFY USER AS PASSWORD=, LOGON HOURS=NULL; to block database login.
4. Optionally execute DROP USER ; after reassigning owned objects.

Watch out for: Setting status to INACTIVE in the REST API does not automatically terminate active database sessions; existing sessions persist until they time out or are killed via ABORT SESSION.

Audit all users and their roles (on-prem)

1. Connect to Teradata Database via JDBC/ODBC with a DBC or admin account.
2. Execute: SELECT UserName, CreatorName, DefaultDatabase, PermSpace FROM DBC.UsersV ORDER BY UserName;
3. Execute: SELECT RoleName, Grantee FROM DBC.RoleMembers ORDER BY RoleName; to list role assignments.
4. Export results to your SIEM or identity governance tool for reconciliation.

Watch out for: DBC system views require SELECT privilege on DBC; grant this carefully as DBC contains sensitive metadata. VantageCloud Lake REST API does not expose an equivalent bulk audit export endpoint.

The most significant architectural trap is assuming the REST API and the SQL DDL layer manage the same user namespace - they do not. A VantageCloud Lake console user and a Teradata database user are separate entities with separate identifiers; userId in the REST API is an internal UUID, not the database username.

Automation that provisions only via REST leaves database-layer access unprovisioned, and automation that provisions only via SQL leaves the user unable to access the console.

No SCIM 2.0 endpoint is documented for VantageCloud Lake or on-prem Teradata. IdP-driven provisioning via Okta or Entra ID requires custom integration against the REST API (for console users) and SQL DDL (for database users) - there is no supported connector path.

An identity graph built on top of Teradata must account for both namespaces explicitly and reconcile them on a scheduled basis, since no event-subscription or webhook mechanism is documented for user management events.

Pagination parameters (page size, offset param name) are not published in official documentation as of the policy date; callers should treat pagination behavior as undocumented and test against their specific environment. Official REST API documentation is partially gated behind the Teradata customer portal, meaning some endpoint details may not be accessible without a support login.