Skip to main content

Authorization API

The Authorization API provides endpoints for managing permission constraints, roles, user-role assignments, Cognito user management, and API keys. These resources control access to all VAMS functionality through a two-tier Casbin ABAC/RBAC authorization model.

Two-tier authorization

VAMS enforces authorization at two levels:

  • Tier 1 (API-level): Controls which API routes a role can access.
  • Tier 2 (Object-level): Controls which data entities (databases, assets, pipelines, etc.) a role can access.

Both tiers must allow access for a request to succeed.

Constraints​

Constraints define the authorization policies that determine what actions users and groups can perform on specific resource types.

List constraints​

Retrieves all permission constraints.

GET /auth/constraints

Response​

{
    "message": {
        "Items": [
            {
                "constraintId": "constraint-abc123#group#admin-role",
                "name": "Admin Full Access",
                "description": "Full access to all resources",
                "objectType": "asset",
                "criteriaAnd": "[{\"field\": \"databaseId\", \"value\": \"*\", \"operator\": \"equals\"}]",
                "criteriaOr": "[]",
                "groupPermissions": "[{\"groupId\": \"admin-role\", \"permission\": \"Read/Write\", \"permissionType\": \"allow\"}]",
                "userPermissions": "[]",
                "dateCreated": "2026-03-15T10:30:00",
                "dateModified": "2026-03-15T10:30:00"
            }
        ]
    }
}

Error responses​

StatusDescription
403Not authorized
500Internal server error

Get a constraint​

Retrieves a specific constraint by ID.

GET /auth/constraints/{constraintId}

Path parameters​

ParameterTypeRequiredDescription
constraintIdstringYesConstraint identifier

Create a constraint​

Creates a new permission constraint.

POST /auth/constraints/{constraintId}

Path parameters​

ParameterTypeRequiredDescription
constraintIdstringYesUnique constraint identifier

Request body​

FieldTypeRequiredDescription
namestringYesHuman-readable name for the constraint
descriptionstringNoDescription of the constraint's purpose
objectTypestringYesResource type this constraint applies to (e.g., asset, database, pipeline, workflow, api, web, tag, tagType, role, userRole, metadataSchema, apiKey)
criteriaAndarrayNoAND criteria for matching resources
criteriaOrarrayNoOR criteria for matching resources
groupPermissionsarrayYesPermissions granted to roles/groups
userPermissionsarrayNoPermissions granted to specific users

Each entry in groupPermissions:

FieldTypeRequiredDescription
groupIdstringYesRole/group name
permissionstringYesPermission level (Read, Read/Write)
permissionTypestringYesallow or deny

Each entry in criteriaAnd or criteriaOr:

FieldTypeRequiredDescription
fieldstringYesField to match (e.g., databaseId, assetType)
valuestringYesValue to match against (supports * wildcard)
operatorstringYesComparison operator (equals, contains, etc.)

Request body example​

{
    "name": "Database Reader",
    "description": "Read-only access to assets in the production database",
    "objectType": "asset",
    "criteriaAnd": [
        {
            "field": "databaseId",
            "value": "production-db",
            "operator": "equals"
        }
    ],
    "criteriaOr": [],
    "groupPermissions": [
        {
            "groupId": "viewer-role",
            "permission": "Read",
            "permissionType": "allow"
        }
    ],
    "userPermissions": []
}

Response​

{
    "message": "Constraint created successfully"
}

Update a constraint​

Updates an existing constraint.

PUT /auth/constraints/{constraintId}

Path parameters​

ParameterTypeRequiredDescription
constraintIdstringYesConstraint identifier

Request body​

Same structure as Create a constraint.

Delete a constraint​

Deletes a permission constraint.

DELETE /auth/constraints/{constraintId}

Path parameters​

ParameterTypeRequiredDescription
constraintIdstringYesConstraint identifier

Response​

{
    "message": "Constraint deleted successfully"
}

Import constraint template​

Imports a constraint configuration from a JSON template file. This is useful for bulk-provisioning permissions.

POST /auth/constraintsTemplateImport

Request body​

The request body should contain the full constraint template JSON. See the permission templates in documentation/permissionsTemplates/ for examples.

Response​

{
    "message": "Template imported successfully"
}

Roles​

Roles are named groups that can be assigned to users. Constraints reference roles via groupPermissions to grant or deny access.

List roles​

Retrieves all roles.

GET /roles

Response​

{
    "message": {
        "Items": [
            {
                "roleName": "admin",
                "description": "Full administrative access",
                "dateCreated": "2026-03-15T10:30:00"
            }
        ]
    }
}

Create a role​

Creates a new role.

POST /roles

Request body​

FieldTypeRequiredDescription
roleNamestringYesUnique role name
descriptionstringNoRole description

Request body example​

{
    "roleName": "viewer",
    "description": "Read-only access to assets and databases"
}

Response​

{
    "message": "Role created successfully"
}

Update a role​

Updates an existing role.

PUT /roles

Request body​

Same structure as Create a role.

Delete a role​

Deletes a role.

DELETE /roles/{roleId}

Path parameters​

ParameterTypeRequiredDescription
roleIdstringYesRole name to delete
warning

Deleting a role does not automatically remove user-role assignments referencing this role. Clean up user-role assignments before or after deleting the role.

Response​

{
    "message": "Role deleted successfully"
}

User-role assignments​

User-role assignments link users to roles. A user can have multiple roles, and each role's constraints combine to determine the user's effective permissions.

List user-role assignments​

Retrieves all user-role assignments.

GET /user-roles

Response​

{
    "message": {
        "Items": [
            {
                "userId": "user@example.com",
                "roleName": "admin"
            }
        ]
    }
}

Assign a role to a user​

Creates a new user-role assignment.

POST /user-roles

Request body​

FieldTypeRequiredDescription
userIdstringYesUser identifier
roleNamestringYesRole name to assign

Request body example​

{
    "userId": "user@example.com",
    "roleName": "viewer"
}

Response​

{
    "message": "User role assignment created successfully"
}

Update a user-role assignment​

Updates an existing user-role assignment.

PUT /user-roles

Request body​

Same structure as Assign a role to a user.

Remove a role from a user​

Removes a user-role assignment.

DELETE /user-roles

Request body​

FieldTypeRequiredDescription
userIdstringYesUser identifier
roleNamestringYesRole name to remove

Request body example​

{
    "userId": "user@example.com",
    "roleName": "viewer"
}

Response​

{
    "message": "User role assignment deleted successfully"
}

Cognito user management​

These endpoints manage users in the Amazon Cognito user pool. They are only available when Cognito authentication is enabled in the deployment.

Cognito required

These endpoints return an error if Cognito is not enabled in the deployment configuration (app.authProvider.useCognito.enabled).

List Cognito users​

GET /user/cognito

Response​

{
    "message": {
        "users": [
            {
                "userId": "user@example.com",
                "email": "user@example.com",
                "status": "CONFIRMED",
                "enabled": true,
                "dateCreated": "2026-03-15T10:30:00Z"
            }
        ]
    }
}

Create a Cognito user​

POST /user/cognito

Request body​

FieldTypeRequiredDescription
userIdstringYesUsername for the new user
emailstringYesEmail address

Request body example​

{
    "userId": "newuser@example.com",
    "email": "newuser@example.com"
}

Update a Cognito user​

PUT /user/cognito/{userId}

Path parameters​

ParameterTypeRequiredDescription
userIdstringYesUser identifier

Request body​

FieldTypeRequiredDescription
emailstringNoUpdated email address
enabledbooleanNoEnable or disable the user

Delete a Cognito user​

DELETE /user/cognito/{userId}

Path parameters​

ParameterTypeRequiredDescription
userIdstringYesUser identifier to delete

Reset a user's password​

Sends a password reset to the specified Cognito user.

POST /user/cognito/{userId}/resetPassword

Path parameters​

ParameterTypeRequiredDescription
userIdstringYesUser identifier

Response​

{
    "message": "Password reset initiated successfully"
}

API keys​

API keys provide programmatic access to VAMS without requiring interactive authentication.

List API keys​

GET /auth/api-keys

Response​

{
    "message": {
        "Items": [
            {
                "apiKeyId": "key-abc123",
                "name": "CI/CD Pipeline Key",
                "userId": "service-account@example.com",
                "enabled": true,
                "dateCreated": "2026-03-15T10:30:00Z",
                "expiresAt": "2027-03-15T10:30:00Z"
            }
        ]
    }
}
note

The API key secret value is only returned once during creation and cannot be retrieved afterwards.

Get a specific API key​

GET /auth/api-keys/{apiKeyId}

Path parameters​

ParameterTypeRequiredDescription
apiKeyIdstringYesAPI key identifier

Create an API key​

POST /auth/api-keys

Request body​

FieldTypeRequiredDescription
namestringYesDisplay name for the API key
userIdstringYesUser to associate the key with
expiresAtstringNoExpiration date (ISO 8601)

Request body example​

{
    "name": "CI/CD Pipeline Key",
    "userId": "service-account@example.com",
    "expiresAt": "2027-03-15T10:30:00Z"
}

Response​

{
    "message": {
        "apiKeyId": "key-abc123",
        "apiKeySecret": "vams_ak_xxxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "CI/CD Pipeline Key",
        "userId": "service-account@example.com"
    }
}
Store the secret securely

The apiKeySecret value is only returned during creation. Store it securely -- it cannot be retrieved again.

Update an API key​

PUT /auth/api-keys/{apiKeyId}

Path parameters​

ParameterTypeRequiredDescription
apiKeyIdstringYesAPI key identifier

Request body​

FieldTypeRequiredDescription
namestringNoUpdated display name
enabledbooleanNoEnable or disable the key
expiresAtstringNoUpdated expiration date

Delete an API key​

DELETE /auth/api-keys/{apiKeyId}

Path parameters​

ParameterTypeRequiredDescription
apiKeyIdstringYesAPI key identifier

Response​

{
    "message": "API key deleted successfully"
}
  • Assets API -- Resources protected by these authorization policies
  • Pipelines API -- Pipeline access controlled by constraints
  • Workflows API -- Workflow access controlled by constraints