ApiToken

Represents an individual access token issued from an ApiKey for authenticating API requests. Supports multiple token types (Bearer, JWT, HMAC, Basic) with independent lifecycle management, expiration policies, and security monitoring including IP tracking and usage analytics. Each token inherits scope permissions from its parent ApiKey but can be further restricted for principle of least privilege.

20 properties

Schema

Properties

Property	Type	Mode	Description	Required
tokenId	string	stored	Unique identifier for this token (used for lookups and revocation) Example: `"tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"`	Required
apiKey	ApiKey	stored	Reference to the parent ApiKey from which this token was issued	Required
tokenHash	string	stored	Cryptographic hash of the actual token value (SHA-256 or bcrypt, never store plaintext) Example: `"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"`	Required
tokenType	string	stored	Type of authentication token issued Values: `bearer, jwt, hmac, basic` Example: `"bearer"`	Required
status	string	stored	Current lifecycle status of this token Values: `active, revoked, expired` Example: `"active"`	Required
issuedAt	datetime	stored	Date/time when this token was originally issued Example: `"2024-11-22T10:30:00Z"`	Required
expiresAt	datetime	stored	Date/time when this token will expire and become invalid Example: `"2024-12-22T10:30:00Z"`	Required
lastAccessedAt	datetime	stored	Date/time of the most recent API request using this token Example: `"2024-11-27T14:25:00Z"`	Optional
revokedAt	datetime	stored	Date/time when this token was manually revoked before expiration Example: `"2024-11-25T09:15:00Z"`	Optional
sourceIp	string	stored	IP address from which this token was first issued (for security tracking) Example: `"203.0.113.45"`	Optional
userAgent	string	stored	User agent string of the client that requested this token Example: `"MyAPIClient/2.1.0 (Linux x86_64)"`	Optional
location	json	stored	Geographic location derived from source IP address including country, region, city	Optional
accessCount	number	stored	Total number of successful API requests made using this token Example: `1247`	Required
grantedScopes	string[]	stored	OAuth scopes granted to this token (must be subset of parent ApiKey's allowedScopes) Example: `["api:read","webhooks:write"]`	Optional
revokeReason	string	stored	Reason why this token was revoked before natural expiration Values: `user-requested, security-incident, key-rotation, suspicious-activity, key-revoked, admin-action` Example: `"key-rotation"`	Optional
metadata	json	stored	Additional token metadata including client context, environment details, or custom attributes	Optional
isActive	boolean	calculated	Whether this token is currently active (not expired, not revoked, and parent key is active)	Optional
isExpired	boolean	calculated	Whether this token has passed its expiration date	Optional
durationMinutes	number	calculated	Token validity duration in minutes from issuedAt to expiresAt	Optional
idleMinutes	number	calculated	Minutes since the last API access using this token (for idle timeout detection)	Optional

Examples

Example 1

{
  "@type": "ApiToken",
  "tokenId": "tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "apiKey": {
    "@type": "ApiKey",
    "keyId": "key_prod_xyz789abc123"
  },
  "tokenHash": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "tokenType": "bearer",
  "status": "active",
  "issuedAt": "2024-11-22T10:30:00Z",
  "expiresAt": "2024-12-22T10:30:00Z",
  "lastAccessedAt": "2024-11-27T14:25:00Z",
  "sourceIp": "203.0.113.45",
  "userAgent": "MyAPIClient/2.1.0 (Linux x86_64)",
  "location": {
    "country": "United States",
    "region": "California",
    "city": "San Francisco"
  },
  "accessCount": 1247,
  "grantedScopes": [
    "api:read",
    "api:write",
    "webhooks:write"
  ],
  "metadata": {
    "environment": "production",
    "clientId": "client-app-001"
  }
}

Example 2

{
  "@type": "ApiToken",
  "tokenId": "tok_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
  "apiKey": {
    "@type": "ApiKey",
    "keyId": "key_svc_integration_456"
  },
  "tokenHash": "7d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9",
  "tokenType": "jwt",
  "status": "active",
  "issuedAt": "2024-11-01T00:00:00Z",
  "expiresAt": "2025-11-01T00:00:00Z",
  "lastAccessedAt": "2024-11-27T15:10:00Z",
  "sourceIp": "10.0.1.50",
  "userAgent": "ServiceClient/3.0.0 Node.js/20.10.0",
  "location": {
    "country": "United States",
    "region": "Virginia",
    "city": "Ashburn"
  },
  "accessCount": 8923,
  "grantedScopes": [
    "api:read",
    "api:write",
    "admin:read"
  ],
  "metadata": {
    "serviceType": "backend-integration",
    "serviceName": "data-sync-service",
    "jwtClaims": {
      "iss": "https://api.example.com",
      "sub": "service-account-123",
      "aud": "https://integration-partner.com"
    }
  }
}

Example 3

{
  "@type": "ApiToken",
  "tokenId": "tok_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "apiKey": {
    "@type": "ApiKey",
    "keyId": "key_dev_test123"
  },
  "tokenHash": "3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2",
  "tokenType": "bearer",
  "status": "expired",
  "issuedAt": "2024-10-15T08:00:00Z",
  "expiresAt": "2024-11-15T08:00:00Z",
  "lastAccessedAt": "2024-11-14T23:45:00Z",
  "sourceIp": "198.51.100.78",
  "userAgent": "curl/8.1.2",
  "location": {
    "country": "France",
    "region": "Île-de-France",
    "city": "Paris"
  },
  "accessCount": 342,
  "grantedScopes": [
    "api:read"
  ],
  "metadata": {
    "environment": "development",
    "developerId": "dev-user-789"
  }
}

Example 4

{
  "@type": "ApiToken",
  "tokenId": "tok_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9",
  "apiKey": {
    "@type": "ApiKey",
    "keyId": "key_prod_xyz789abc123"
  },
  "tokenHash": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8",
  "tokenType": "bearer",
  "status": "revoked",
  "issuedAt": "2024-11-20T14:00:00Z",
  "expiresAt": "2024-12-20T14:00:00Z",
  "lastAccessedAt": "2024-11-25T09:10:00Z",
  "revokedAt": "2024-11-25T09:15:00Z",
  "sourceIp": "192.0.2.123",
  "userAgent": "PostmanRuntime/7.35.0",
  "location": {
    "country": "United Kingdom",
    "region": "England",
    "city": "London"
  },
  "accessCount": 45,
  "grantedScopes": [
    "api:read",
    "api:write"
  ],
  "revokeReason": "suspicious-activity",
  "metadata": {
    "securityIncidentId": "inc-2024-1125-001",
    "anomalyDetected": "unusual-access-pattern",
    "revokedBy": "security-automation"
  }
}

Example 5

{
  "@type": "ApiToken",
  "tokenId": "tok_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "apiKey": {
    "@type": "ApiKey",
    "keyId": "key_partner_abc456def789"
  },
  "tokenHash": "1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
  "tokenType": "hmac",
  "status": "active",
  "issuedAt": "2024-11-15T12:00:00Z",
  "expiresAt": "2025-02-15T12:00:00Z",
  "lastAccessedAt": "2024-11-27T11:30:00Z",
  "sourceIp": "198.18.0.45",
  "userAgent": "WebhookClient/1.5.0 (Java 17)",
  "location": {
    "country": "Germany",
    "region": "Bavaria",
    "city": "Munich"
  },
  "accessCount": 523,
  "grantedScopes": [
    "webhooks:write"
  ],
  "metadata": {
    "webhookEndpoint": "https://partner.example.com/webhooks",
    "hmacAlgorithm": "sha256",
    "partnerName": "Integration Partner GmbH"
  }
}