Permission Management

Configure and manage detailed permissions for team members and API keys. TensorOne provides flexible role-based access control with granular permissions for resources, operations, and data access.

Get Permission Schema

Retrieve the complete permission schema and available roles.

curl -X GET "https://api.tensorone.ai/v2/accounts/permissions/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "roles": {
        "owner": {
            "name": "Owner",
            "description": "Full access to all resources and billing",
            "permissions": ["*"],
            "scopes": ["*"],
            "inherits": [],
            "assignable": false
        },
        "admin": {
            "name": "Administrator",
            "description": "Manage all resources and team members",
            "permissions": ["read", "write", "execute", "manage_team", "manage_billing"],
            "scopes": ["endpoints", "clusters", "accounts", "billing"],
            "inherits": ["developer"],
            "assignable": true
        },
        "developer": {
            "name": "Developer",
            "description": "Create and manage AI resources",
            "permissions": ["read", "write", "execute"],
            "scopes": ["endpoints", "clusters"],
            "inherits": ["viewer"],
            "assignable": true
        },
        "viewer": {
            "name": "Viewer",
            "description": "Read-only access to resources",
            "permissions": ["read"],
            "scopes": ["endpoints", "clusters"],
            "inherits": [],
            "assignable": true
        }
    },
    "permissions": {
        "read": "Access to retrieve data and view resources",
        "write": "Create, update, and delete resources",
        "execute": "Run endpoints and execute compute operations",
        "manage_team": "Invite, remove, and manage team members",
        "manage_billing": "Access billing information and payment methods",
        "manage_integrations": "Configure external integrations and webhooks",
        "manage_security": "Configure security settings and audit logs"
    },
    "scopes": {
        "endpoints": "Serverless endpoint management",
        "clusters": "GPU cluster management",
        "accounts": "Account and team management",
        "billing": "Billing and usage information",
        "integrations": "External service integrations",
        "security": "Security and compliance settings"
    }
}

List User Permissions

Get detailed permissions for the current user or a specific team member.

curl -X GET "https://api.tensorone.ai/v2/accounts/permissions/usr_1234567890abcdef" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "userId": "usr_1234567890abcdef",
    "role": "developer",
    "effectivePermissions": {
        "permissions": ["read", "write", "execute"],
        "scopes": ["endpoints", "clusters"],
        "resourceAccess": {
            "endpoints": {
                "own": ["read", "write", "execute", "delete"],
                "team": ["read", "execute"],
                "public": ["read"]
            },
            "clusters": {
                "own": ["read", "write", "delete"],
                "team": ["read", "write"],
                "public": ["read"]
            }
        },
        "limitations": {
            "maxEndpoints": 50,
            "maxClusters": 10,
            "maxComputeHours": 1000,
            "maxTeamMembers": null
        }
    },
    "customPermissions": [],
    "inheritedFrom": ["viewer"],
    "lastUpdated": "2024-03-15T10:30:00Z"
}

Create Custom Role

Create a custom role with specific permissions.

curl -X POST "https://api.tensorone.ai/v2/accounts/permissions/roles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ml_researcher",
    "displayName": "ML Researcher",
    "description": "Research-focused role with execution access",
    "permissions": ["read", "execute"],
    "scopes": ["endpoints"],
    "limitations": {
      "maxEndpoints": 20,
      "maxComputeHours": 500
    },
    "inherits": ["viewer"]
  }'

Request Schema

{
    "name": "string (required, unique identifier)",
    "displayName": "string (required, human-readable name)",
    "description": "string (optional, role description)",
    "permissions": "array (required, permission names)",
    "scopes": "array (required, scope names)",
    "limitations": {
        "maxEndpoints": "number (optional)",
        "maxClusters": "number (optional)",
        "maxComputeHours": "number (optional)",
        "maxApiKeys": "number (optional)"
    },
    "inherits": "array (optional, parent role names)"
}

Response

{
    "role": {
        "id": "role_custom_ml_researcher",
        "name": "ml_researcher",
        "displayName": "ML Researcher",
        "description": "Research-focused role with execution access",
        "permissions": ["read", "execute"],
        "scopes": ["endpoints"],
        "limitations": {
            "maxEndpoints": 20,
            "maxComputeHours": 500
        },
        "inherits": ["viewer"],
        "createdAt": "2024-03-20T15:30:00Z",
        "assignable": true
    }
}

Update Custom Role

Modify an existing custom role’s permissions and settings.

curl -X PUT "https://api.tensorone.ai/v2/accounts/permissions/roles/role_custom_ml_researcher" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Senior ML Researcher",
    "permissions": ["read", "write", "execute"],
    "limitations": {
      "maxEndpoints": 35,
      "maxComputeHours": 750
    }
  }'

Assign Custom Permissions

Grant specific permissions to a user beyond their role.

curl -X POST "https://api.tensorone.ai/v2/accounts/permissions/usr_1234567890abcdef/grant" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["manage_integrations"],
    "scopes": ["integrations"],
    "resources": ["ep_specific_endpoint"],
    "expiresAt": "2024-06-20T15:30:00Z",
    "reason": "Temporary access for Slack integration setup"
  }'

Request Schema

{
    "permissions": "array (required, additional permissions)",
    "scopes": "array (required, permission scopes)",
    "resources": "array (optional, specific resource IDs)",
    "expiresAt": "string (optional, ISO 8601 date)",
    "reason": "string (optional, justification)"
}

Response

{
    "grant": {
        "id": "grant_1234567890abcdef",
        "userId": "usr_1234567890abcdef",
        "permissions": ["manage_integrations"],
        "scopes": ["integrations"],
        "resources": ["ep_specific_endpoint"],
        "expiresAt": "2024-06-20T15:30:00Z",
        "reason": "Temporary access for Slack integration setup",
        "grantedBy": "usr_admin123456789",
        "grantedAt": "2024-03-20T15:30:00Z",
        "status": "active"
    }
}

Revoke Custom Permissions

Remove specific granted permissions from a user.

curl -X DELETE "https://api.tensorone.ai/v2/accounts/permissions/grants/grant_1234567890abcdef" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "grant": {
        "id": "grant_1234567890abcdef",
        "status": "revoked",
        "revokedBy": "usr_admin123456789",
        "revokedAt": "2024-03-20T16:00:00Z"
    }
}

Resource-Level Permissions

Manage permissions for specific resources.

curl -X POST "https://api.tensorone.ai/v2/accounts/permissions/resources/ep_1234567890abcdef/share" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": ["usr_1234567890abcdef", "usr_fedcba0987654321"],
    "permissions": ["read", "execute"],
    "message": "Sharing ML model endpoint for collaboration"
  }'

Request Schema

{
    "users": "array (required, user IDs to share with)",
    "teams": "array (optional, team IDs to share with)",
    "permissions": "array (required, permissions to grant)",
    "expiresAt": "string (optional, ISO 8601 date)",
    "message": "string (optional, sharing message)"
}

Response

{
    "resourceId": "ep_1234567890abcdef",
    "shares": [
        {
            "id": "share_1234567890abcdef",
            "userId": "usr_1234567890abcdef",
            "permissions": ["read", "execute"],
            "sharedAt": "2024-03-20T16:00:00Z",
            "status": "active"
        }
    ],
    "message": "Resource shared successfully"
}

Check Permissions

Verify if a user has specific permissions for resources or operations.

curl -X POST "https://api.tensorone.ai/v2/accounts/permissions/check" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_1234567890abcdef",
    "permission": "execute",
    "scope": "endpoints",
    "resourceId": "ep_specific_endpoint"
  }'

Response

{
    "userId": "usr_1234567890abcdef",
    "permission": "execute",
    "scope": "endpoints",
    "resourceId": "ep_specific_endpoint",
    "allowed": true,
    "source": "role",
    "role": "developer",
    "details": {
        "reason": "User has execute permission through developer role",
        "limitations": {
            "remainingExecutions": 450,
            "maxExecutionsPerHour": 100
        }
    }
}

Permission Audit Log

Retrieve audit logs for permission changes and access events.

curl -X GET "https://api.tensorone.ai/v2/accounts/permissions/audit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G -d "period=30d" -d "type=permission_change"

Query Parameters

period: Time period (1d, 7d, 30d, 90d)
type: Event type (permission_change, access_denied, role_assignment)
userId: Filter by specific user
resourceId: Filter by specific resource

Response

{
    "period": "30d",
    "events": [
        {
            "id": "audit_1234567890abcdef",
            "timestamp": "2024-03-20T15:30:00Z",
            "type": "permission_change",
            "actor": {
                "userId": "usr_admin123456789",
                "name": "Admin User",
                "ipAddress": "192.168.1.100"
            },
            "target": {
                "userId": "usr_1234567890abcdef",
                "name": "John Doe"
            },
            "action": "role_updated",
            "details": {
                "oldRole": "viewer",
                "newRole": "developer",
                "reason": "Promotion to development team"
            }
        },
        {
            "id": "audit_fedcba0987654321",
            "timestamp": "2024-03-19T10:15:00Z",
            "type": "access_denied",
            "actor": {
                "userId": "usr_1234567890abcdef",
                "name": "John Doe",
                "ipAddress": "10.0.0.50"
            },
            "resource": {
                "type": "endpoint",
                "id": "ep_restricted123",
                "name": "Production Model"
            },
            "action": "execute_attempt",
            "details": {
                "reason": "Insufficient permissions",
                "requiredPermission": "execute",
                "userRole": "viewer"
            }
        }
    ],
    "total": 45,
    "summary": {
        "permissionChanges": 12,
        "accessDenied": 23,
        "roleAssignments": 8,
        "resourceShares": 2
    }
}

Code Examples

Python SDK

from tensorone import TensorOneAPI
from datetime import datetime, timedelta

client = TensorOneAPI(api_key="your_api_key")

# Get permission schema
schema = client.accounts.permissions.get_schema()
print("Available roles:")
for role_name, role_info in schema.roles.items():
    print(f"  {role_info.name}: {role_info.description}")

# Check user permissions
permissions = client.accounts.permissions.get_user("usr_1234567890abcdef")
print(f"User role: {permissions.role}")
print(f"Permissions: {permissions.effective_permissions.permissions}")

# Create custom role
custom_role = client.accounts.permissions.create_role(
    name="data_scientist",
    display_name="Data Scientist",
    description="Data analysis with limited compute access",
    permissions=["read", "execute"],
    scopes=["endpoints"],
    limitations={
        "max_endpoints": 15,
        "max_compute_hours": 300
    }
)

# Grant temporary permissions
grant = client.accounts.permissions.grant(
    user_id="usr_1234567890abcdef",
    permissions=["manage_integrations"],
    scopes=["integrations"],
    expires_at=datetime.now() + timedelta(days=30),
    reason="Setting up monitoring integration"
)

# Share resource with team members
client.accounts.permissions.share_resource(
    resource_id="ep_1234567890abcdef",
    users=["usr_alice123", "usr_bob456"],
    permissions=["read", "execute"],
    message="Sharing trained model for evaluation"
)

# Check specific permission
can_execute = client.accounts.permissions.check(
    user_id="usr_1234567890abcdef",
    permission="execute",
    scope="endpoints",
    resource_id="ep_production_model"
)
print(f"Can execute: {can_execute.allowed}")

# Get audit log
audit_log = client.accounts.permissions.get_audit(
    period="7d",
    type="permission_change"
)
print(f"Recent permission changes: {len(audit_log.events)}")

JavaScript SDK

import { TensorOneAPI } from "@tensorone/sdk";

const client = new TensorOneAPI("your_api_key");

// Get permission schema
const schema = await client.accounts.permissions.getSchema();
console.log("Available roles:", Object.keys(schema.roles));

// Check user permissions
const permissions = await client.accounts.permissions.getUser("usr_1234567890abcdef");
console.log(`User role: ${permissions.role}`);
console.log(`Effective permissions:`, permissions.effectivePermissions.permissions);

// Create custom role
const customRole = await client.accounts.permissions.createRole({
    name: "intern",
    displayName: "Intern",
    description: "Limited access for interns",
    permissions: ["read"],
    scopes: ["endpoints"],
    limitations: {
        maxEndpoints: 5,
        maxComputeHours: 50,
    },
    inherits: ["viewer"],
});

// Grant permissions with expiration
const grant = await client.accounts.permissions.grant("usr_1234567890abcdef", {
    permissions: ["write"],
    scopes: ["endpoints"],
    resources: ["ep_training_data"],
    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
    reason: "Temporary write access for data cleanup",
});

// Share resource
await client.accounts.permissions.shareResource("ep_1234567890abcdef", {
    users: ["usr_teammate1", "usr_teammate2"],
    permissions: ["read", "execute"],
    message: "Sharing model for peer review",
});

// Check permission
const check = await client.accounts.permissions.check({
    userId: "usr_1234567890abcdef",
    permission: "write",
    scope: "clusters",
    resourceId: "cluster_prod_gpu",
});
console.log(`Write access allowed: ${check.allowed}`);

// Get audit events
const audit = await client.accounts.permissions.getAudit({
    period: "7d",
    type: "access_denied",
});
console.log(`Access denied events: ${audit.events.length}`);

Error Responses

400 Bad Request

{
    "error": "INVALID_PERMISSION",
    "message": "Invalid permission specified",
    "details": {
        "invalidPermissions": ["invalid_perm"],
        "validPermissions": ["read", "write", "execute", "manage_team", "manage_billing"]
    }
}

403 Forbidden

{
    "error": "INSUFFICIENT_PERMISSIONS",
    "message": "Cannot grant permissions higher than your own",
    "details": {
        "attemptedPermission": "manage_billing",
        "userRole": "developer",
        "requiredRole": "admin"
    }
}

409 Conflict

{
    "error": "ROLE_NAME_EXISTS",
    "message": "Custom role name already exists",
    "details": {
        "roleName": "ml_researcher",
        "existingRoleId": "role_custom_ml_researcher"
    }
}

422 Unprocessable Entity

{
    "error": "INVALID_ROLE_HIERARCHY",
    "message": "Cannot inherit from a role with higher permissions",
    "details": {
        "parentRole": "admin",
        "childRole": "custom_viewer",
        "reason": "Child role cannot have fewer permissions than parent"
    }
}

Security Best Practices

Role Design

Use the principle of least privilege
Create specific roles for different job functions
Regularly review and audit custom roles
Avoid granting broad permissions unnecessarily

Permission Grants

Use temporary permissions with expiration dates
Document reasons for permission grants
Regular cleanup of expired or unused grants
Monitor permission usage through audit logs

Share resources with specific permissions only
Use expiration dates for temporary collaborations
Track resource access through audit logs
Regular review of shared resources

Use Cases

Team Onboarding

def setup_intern_permissions():
    # Create intern role with limited access
    intern_role = client.accounts.permissions.create_role(
        name="intern",
        display_name="Intern",
        description="Limited access for learning",
        permissions=["read"],
        scopes=["endpoints"],
        limitations={
            "max_endpoints": 3,
            "max_compute_hours": 20
        }
    )

    # Grant temporary additional access for specific project
    client.accounts.permissions.grant(
        user_id="usr_intern123",
        permissions=["execute"],
        scopes=["endpoints"],
        resources=["ep_training_model"],
        expires_at=datetime.now() + timedelta(weeks=2),
        reason="Intern project on image classification"
    )

Project Collaboration

def setup_project_collaboration(project_endpoints, team_members):
    # Share all project endpoints with team
    for endpoint_id in project_endpoints:
        client.accounts.permissions.share_resource(
            resource_id=endpoint_id,
            users=team_members,
            permissions=["read", "execute"],
            expires_at=datetime.now() + timedelta(months=3),
            message="Shared for Q2 AI project collaboration"
        )

    # Grant temporary write access to lead developer
    client.accounts.permissions.grant(
        user_id="usr_lead_dev",
        permissions=["write"],
        scopes=["endpoints"],
        resources=project_endpoints,
        expires_at=datetime.now() + timedelta(months=3),
        reason="Lead developer needs to modify project endpoints"
    )

Compliance Auditing

def compliance_audit_report():
    # Get all permission changes in last 90 days
    audit_log = client.accounts.permissions.get_audit(
        period="90d",
        type="permission_change"
    )

    # Analyze permission grants without expiration
    grants_without_expiry = []
    for event in audit_log.events:
        if event.action == "permission_granted" and not event.details.get("expiresAt"):
            grants_without_expiry.append(event)

    # Check for overprivileged users
    members = client.accounts.team.members.list()
    for member in members:
        permissions = client.accounts.permissions.get_user(member.id)
        if len(permissions.effective_permissions.permissions) > 3:
            print(f"Review permissions for {member.name}: {permissions.effective_permissions.permissions}")

    return {
        "total_changes": len(audit_log.events),
        "grants_without_expiry": len(grants_without_expiry),
        "overprivileged_users": len([m for m in members if len(m.permissions) > 3])
    }

Permission Cleanup

def cleanup_expired_permissions():
    # Get audit log to find expired grants
    audit_log = client.accounts.permissions.get_audit(
        period="30d",
        type="permission_grant"
    )

    now = datetime.now()
    expired_grants = []

    for event in audit_log.events:
        if event.details.get("expiresAt"):
            expires_at = datetime.fromisoformat(event.details["expiresAt"])
            if expires_at < now:
                expired_grants.append(event.details["grantId"])

    # Revoke expired grants
    for grant_id in expired_grants:
        try:
            client.accounts.permissions.revoke_grant(grant_id)
            print(f"Revoked expired grant: {grant_id}")
        except Exception as e:
            print(f"Failed to revoke {grant_id}: {e}")

    return len(expired_grants)

Authorizations

Authorization

string

header

required

API key authentication. Use 'Bearer YOUR_API_KEY' format.

Body

application/json

Response

201 - application/json

Permissions granted successfully

The response is of type object.

Getting Started

Account Management

GPU Clusters (VPS)

Serverless Endpoints

Managed Training

AI Services

Payment & Billing

Monitoring & Analytics

​Get Permission Schema

​Response

​List User Permissions

​Response

​Create Custom Role

​Request Schema

​Response

​Update Custom Role

​Assign Custom Permissions

​Request Schema

​Response

​Revoke Custom Permissions

​Response

​Resource-Level Permissions

​Request Schema

​Response

​Check Permissions

​Response

​Permission Audit Log

​Query Parameters

​Response

​Code Examples

​Python SDK

​JavaScript SDK

​Error Responses

​400 Bad Request

​403 Forbidden

​409 Conflict

​422 Unprocessable Entity

​Security Best Practices

​Role Design

​Permission Grants

​Resource Sharing

​Use Cases

​Team Onboarding

​Project Collaboration

​Compliance Auditing

​Permission Cleanup

Authorizations

Body

Response

Get Permission Schema

Response

List User Permissions

Response

Create Custom Role

Request Schema

Response

Update Custom Role

Assign Custom Permissions

Request Schema

Response

Revoke Custom Permissions

Response

Resource-Level Permissions

Request Schema

Response

Check Permissions

Response

Permission Audit Log

Query Parameters

Response

Code Examples

Python SDK

JavaScript SDK

Error Responses

400 Bad Request

403 Forbidden

409 Conflict

422 Unprocessable Entity

Security Best Practices

Role Design

Permission Grants

Resource Sharing

Use Cases

Team Onboarding

Project Collaboration

Compliance Auditing

Permission Cleanup