Token Management

Personal Access Tokens and OAuth Client management endpoints

The Token Management API allows you to create and manage authentication methods including Personal Access Tokens (PATs) and OAuth clients. PATs provide a simpler authentication method for scripts and automation, while OAuth clients enable third-party integrations.

Personal Access Tokens vs OAuth:

• PATs are simpler - no OAuth flow required
• PATs don't expire automatically (unless you set an expiration)
• PATs are perfect for scripts, CI/CD, and personal projects
• OAuth tokens are better for user-facing applications that need automatic refresh

Available Endpoints

Complete list of token management endpoints:

Endpoint	Method	Purpose	Required Scope
/api/user/tokens	GET	List personal access tokens	tokens:read
/api/user/tokens	POST	Create personal access token	tokens:write
/api/user/tokens/:id	GET	Get token details	tokens:read
/api/user/tokens/:id	DELETE	Revoke personal access token	tokens:delete
/api/user/oauth-clients	GET	List OAuth clients	tokens:read
/api/user/oauth-clients	POST	Create OAuth client	tokens:write
/api/user/oauth-clients/:id	GET	Get OAuth client details	tokens:read
/api/user/oauth-clients/:id	PUT	Update OAuth client	tokens:write
/api/user/oauth-clients/:id	DELETE	Delete OAuth client	tokens:delete
/api/user/oauth-clients/:id/regenerate-secret	POST	Regenerate client secret	tokens:write

Personal Access Tokens

Personal Access Tokens (PATs) provide a simpler authentication method for scripts and applications. Unlike OAuth tokens, PATs don't expire automatically and don't require the OAuth flow.

GET /api/user/tokens

List all personal access tokens for the authenticated user.

Required Scope: tokens:read

Request:

curl -X GET https://api.tinyrebrand.com/api/user/tokens \
  -H "Authorization: Bearer at_1234567890abcdef"

Parameters:

Parameter	Type	Required	Description
start	number	❌	Pagination offset (default: 0)
limit	number	❌	Number of results (default: 10, max: 100)

Response:

{
  "status": 200,
  "code": "OK",
  "message": "Personal access tokens retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "CI/CD Pipeline",
      "description": "Token for automated deployments",
      "scopes": ["links:read", "links:write"],
      "lastUsedAt": "2024-07-01T10:30:00.000Z",
      "createdAt": "2024-01-15T08:00:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "start": 0,
    "limit": 10
  }
}

POST /api/user/tokens

Create a new personal access token.

Required Scope: tokens:write

Request:

curl -X POST https://api.tinyrebrand.com/api/user/tokens \
  -H "Authorization: Bearer at_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Token",
    "description": "Token for my application",
    "scopes": ["links:read", "links:write", "stats:read"],
    "expiresAt": "2025-01-01T00:00:00.000Z"
  }'

Parameters:

Parameter	Type	Required	Description
name	string	✅	Unique name for the token (max 100 chars)
description	string	❌	Token description (max 500 chars)
scopes	string[]	✅	Array of permission scopes
expiresAt	string	❌	Optional expiration date (ISO 8601)

Response:

{
  "status": 200,
  "code": "OK",
  "message": "Personal access token created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439012",
    "name": "My API Token",
    "description": "Token for my application",
    "scopes": ["links:read", "links:write", "stats:read"],
    "token": "tkn_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789",
    "expiresAt": "2025-01-01T00:00:00.000Z",
    "createdAt": "2024-07-02T12:00:00.000Z"
  }
}

Notes:

The token value is only shown once during creation. Store it securely.
Tokens are prefixed with 'tkn_' for easy identification.
Maximum 10 active tokens per user.

GET /api/user/tokens/:id

Get details of a specific personal access token.

Required Scope: tokens:read

Request:

curl -X GET https://api.tinyrebrand.com/api/user/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer at_1234567890abcdef"

Response:

{
  "status": 200,
  "code": "OK",
  "message": "Personal access token retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "CI/CD Pipeline",
    "description": "Token for automated deployments",
    "scopes": ["links:read", "links:write"],
    "lastUsedAt": "2024-07-01T10:30:00.000Z",
    "expiresAt": null,
    "isActive": true,
    "isExpired": false,
    "createdAt": "2024-01-15T08:00:00.000Z",
    "updatedAt": "2024-07-01T10:30:00.000Z"
  }
}

DELETE /api/user/tokens/:id

Revoke a personal access token.

Required Scope: tokens:delete

Request:

curl -X DELETE https://api.tinyrebrand.com/api/user/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer at_1234567890abcdef"

Response:

{
  "status": 200,
  "code": "OK",
  "message": "Personal access token revoked successfully"
}

Notes:

Revoked tokens cannot be restored.
You cannot revoke the token you're currently using.

OAuth Clients

OAuth clients enable third-party applications to authenticate with TinyRebrand. Each client has a unique ID and secret, and can be configured with specific scopes and redirect URIs.

GET /api/user/oauth-clients

List all OAuth clients for the authenticated user.

Required Scope: tokens:read

Request:

curl -X GET https://api.tinyrebrand.com/api/user/oauth-clients \
  -H "Authorization: Bearer at_1234567890abcdef"

Parameters:

Parameter	Type	Required	Description
q	string	❌	Search query for client name
start	number	❌	Pagination offset
limit	number	❌	Number of results

Response:

{
  "status": 200,
  "code": "OK",
  "message": "OAuth clients found successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439013",
      "clientId": "client_abc123",
      "name": "My App",
      "description": "Third-party integration",
      "scopes": ["links:read", "links:write"],
      "redirectUris": ["https://myapp.com/callback"],
      "isActive": true,
      "createdAt": "2024-01-15T08:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "start": 0,
    "limit": 10
  }
}

POST /api/user/oauth-clients

Create a new OAuth client.

Required Scope: tokens:write

Request:

curl -X POST https://api.tinyrebrand.com/api/user/oauth-clients \
  -H "Authorization: Bearer at_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "description": "Third-party integration",
    "scopes": ["links:read", "links:write"],
    "redirectUris": ["https://myapp.com/callback"]
  }'

Parameters:

Parameter	Type	Required	Description
name	string	✅	Client name
description	string	❌	Client description
scopes	string[]	✅	Array of allowed scopes
redirectUris	string[]	✅	Array of valid redirect URIs

Response:

{
  "status": 200,
  "code": "OK",
  "message": "OAuth client created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "clientId": "client_xyz789",
    "clientSecret": "secret_abcdef123456",
    "name": "My App",
    "description": "Third-party integration",
    "scopes": ["links:read", "links:write"],
    "redirectUris": ["https://myapp.com/callback"],
    "isActive": true,
    "createdAt": "2024-07-02T12:00:00.000Z"
  }
}

Notes:

The client secret is only shown once during creation.
Store the client ID and secret securely.

POST /api/user/oauth-clients/:id/regenerate-secret

Regenerate the client secret for an OAuth client.

Required Scope: tokens:write

Request:

curl -X POST https://api.tinyrebrand.com/api/user/oauth-clients/507f1f77bcf86cd799439013/regenerate-secret \
  -H "Authorization: Bearer at_1234567890abcdef"

Response:

{
  "status": 200,
  "code": "OK",
  "message": "Client secret regenerated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439013",
    "clientId": "client_abc123",
    "clientSecret": "secret_newSecret789",
    "name": "My App",
    "isActive": true
  }
}

Notes:

The old secret becomes invalid immediately.
The new secret is only shown once.

User Endpoints

Links Endpoints