AuthorizationGrant

Represents an OAuth 2.0 authorization grant enabling delegated access to protected resources. Manages authorization codes, client credentials, refresh tokens, and consent with granted scopes and lifecycle tracking. Supports fine-grained consent management and scope-based access control for OAuth 2.0 and OpenID Connect flows.

24 properties

Schema

Properties

Property	Type	Mode	Description	Required
user	User	stored	Reference to the User (resource owner) who authorized this grant	Optional
client	OAuthClient	stored	Reference to the OAuthClient application that received this authorization grant	Required
grantType	string	stored	OAuth 2.0 grant type used for this authorization Values: `authorization_code, client_credentials, refresh_token, implicit, password, device_code` Example: `"authorization_code"`	Required
code	string	stored	Authorization code issued (for authorization_code grant type) - short-lived and single-use Example: `"auth_code_a1b2c3d4e5f6g7h8i9j0"`	Optional
codeChallenge	string	stored	PKCE code challenge for enhanced security (prevents authorization code interception) Example: `"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"`	Optional
codeChallengeMethod	string	stored	Method used for PKCE code challenge Values: `plain, S256` Example: `"S256"`	Optional
scopes	string[]	stored	OAuth scopes granted by the user for this authorization Example: `["openid","profile","email","api:read"]`	Required
status	string	stored	Current status of this authorization grant Values: `pending, active, consumed, expired, revoked` Example: `"active"`	Required
redirectUri	string	stored	Redirect URI used during authorization (must match client's registered URIs) Example: `"https://app.example.com/callback"`	Optional
consentedAt	datetime	stored	Date/time when the user granted consent for this authorization Example: `"2024-11-22T08:10:00Z"`	Optional
issuedAt	datetime	stored	Date/time when this grant was issued by the authorization server Example: `"2024-11-22T08:10:15Z"`	Required
expiresAt	datetime	stored	Date/time when this grant expires (authorization codes expire quickly, typically 10 minutes) Example: `"2024-11-22T08:20:15Z"`	Required
consumedAt	datetime	stored	Date/time when this grant was exchanged for tokens (authorization codes are single-use) Example: `"2024-11-22T08:11:00Z"`	Optional
revokedAt	datetime	stored	Date/time when this grant was revoked (user consent withdrawal or security incident) Example: `"2024-11-23T10:00:00Z"`	Optional
revokeReason	string	stored	Reason for grant revocation Values: `user-request, admin-revoke, security-incident, client-deactivated, scope-change` Example: `"user-request"`	Optional
state	string	stored	OAuth state parameter for CSRF protection (opaque value from client) Example: `"state_x1y2z3a4b5c6d7e8f9g0"`	Optional
nonce	string	stored	OpenID Connect nonce for replay protection (included in ID token) Example: `"nonce_a1b2c3d4e5f6g7h8i9j0"`	Optional
audience	string[]	stored	Target audience/resource servers for this grant (OAuth 2.0 Resource Indicators) Example: `["https://api.example.com","https://data.example.com"]`	Optional
authenticationMethod	AuthenticationMethod	stored	Reference to AuthenticationMethod used when establishing this grant	Optional
consentDecision	json	stored	User's consent decisions for individual scopes and optional claims including approved scopes, denied scopes, remember consent flag	Optional
metadata	json	stored	Additional grant metadata including device info, IP address, protocol details, or custom attributes	Optional
isExpired	boolean	calculated	Whether this grant has expired based on expiresAt timestamp	Optional
isActive	boolean	calculated	Whether this grant is currently active and can be used	Optional
durationMinutes	number	calculated	Grant lifetime in minutes from issuance to expiration	Optional

Examples

Example 1

{
  "@type": "AuthorizationGrant",
  "user": {
    "@type": "User",
    "username": "john.doe"
  },
  "client": {
    "@type": "OAuthClient",
    "clientId": "webapp_abc123"
  },
  "grantType": "authorization_code",
  "code": "auth_code_a1b2c3d4e5f6g7h8i9j0",
  "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "codeChallengeMethod": "S256",
  "scopes": [
    "openid",
    "profile",
    "email",
    "api:read",
    "api:write"
  ],
  "status": "consumed",
  "redirectUri": "https://app.example.com/callback",
  "consentedAt": "2024-11-22T08:10:00Z",
  "issuedAt": "2024-11-22T08:10:15Z",
  "expiresAt": "2024-11-22T08:20:15Z",
  "consumedAt": "2024-11-22T08:11:00Z",
  "state": "state_x1y2z3a4b5c6d7e8f9g0",
  "nonce": "nonce_a1b2c3d4e5f6g7h8i9j0",
  "audience": [
    "https://api.example.com"
  ],
  "authenticationMethod": {
    "@type": "AuthenticationMethod",
    "name": "password-mfa"
  },
  "consentDecision": {
    "approvedScopes": [
      "openid",
      "profile",
      "email",
      "api:read",
      "api:write"
    ],
    "deniedScopes": [],
    "rememberConsent": true
  },
  "metadata": {
    "ipAddress": "203.0.113.45",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  }
}

Example 2

{
  "@type": "AuthorizationGrant",
  "client": {
    "@type": "OAuthClient",
    "clientId": "service_xyz789"
  },
  "grantType": "client_credentials",
  "scopes": [
    "api:read",
    "api:write",
    "data:import"
  ],
  "status": "active",
  "issuedAt": "2024-11-22T00:00:00Z",
  "expiresAt": "2024-11-23T00:00:00Z",
  "audience": [
    "https://api.example.com"
  ],
  "metadata": {
    "ipAddress": "10.0.1.50",
    "clientType": "backend-service"
  }
}

Example 3

{
  "@type": "AuthorizationGrant",
  "user": {
    "@type": "User",
    "username": "jane.smith"
  },
  "client": {
    "@type": "OAuthClient",
    "clientId": "mobile_def456"
  },
  "grantType": "authorization_code",
  "code": "auth_code_b2c3d4e5f6g7h8i9j0k1",
  "codeChallenge": "F9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cN",
  "codeChallengeMethod": "S256",
  "scopes": [
    "openid",
    "profile",
    "email",
    "offline_access"
  ],
  "status": "consumed",
  "redirectUri": "com.example.app://callback",
  "consentedAt": "2024-11-21T16:40:00Z",
  "issuedAt": "2024-11-21T16:40:30Z",
  "expiresAt": "2024-11-21T16:50:30Z",
  "consumedAt": "2024-11-21T16:41:00Z",
  "state": "state_y2z3a4b5c6d7e8f9g0h1",
  "nonce": "nonce_b2c3d4e5f6g7h8i9j0k1",
  "authenticationMethod": {
    "@type": "AuthenticationMethod",
    "name": "federated-oidc"
  },
  "consentDecision": {
    "approvedScopes": [
      "openid",
      "profile",
      "email",
      "offline_access"
    ],
    "deniedScopes": [],
    "rememberConsent": false
  },
  "metadata": {
    "ipAddress": "198.51.100.78",
    "userAgent": "MyApp/2.1.0 (iPhone; iOS 17.0)",
    "deviceId": "device_abc123"
  }
}

Example 4

{
  "@type": "AuthorizationGrant",
  "user": {
    "@type": "User",
    "username": "bob.wilson"
  },
  "client": {
    "@type": "OAuthClient",
    "clientId": "partner_ghi789"
  },
  "grantType": "authorization_code",
  "scopes": [
    "openid",
    "profile",
    "api:read"
  ],
  "status": "revoked",
  "redirectUri": "https://partner.example.com/oauth/callback",
  "consentedAt": "2024-11-15T10:00:00Z",
  "issuedAt": "2024-11-15T10:00:30Z",
  "expiresAt": "2024-11-15T10:10:30Z",
  "consumedAt": "2024-11-15T10:01:00Z",
  "revokedAt": "2024-11-20T14:30:00Z",
  "revokeReason": "user-request",
  "state": "state_z3a4b5c6d7e8f9g0h1i2",
  "consentDecision": {
    "approvedScopes": [
      "openid",
      "profile",
      "api:read"
    ],
    "deniedScopes": [
      "api:write"
    ],
    "rememberConsent": true
  }
}

Example 5

{
  "@type": "AuthorizationGrant",
  "user": {
    "@type": "User",
    "username": "alice.brown"
  },
  "client": {
    "@type": "OAuthClient",
    "clientId": "spa_jkl012"
  },
  "grantType": "authorization_code",
  "code": "auth_code_c3d4e5f6g7h8i9j0k1l2",
  "codeChallenge": "G9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cO",
  "codeChallengeMethod": "S256",
  "scopes": [
    "openid",
    "email"
  ],
  "status": "expired",
  "redirectUri": "https://spa.example.com/auth/callback",
  "consentedAt": "2024-11-22T07:00:00Z",
  "issuedAt": "2024-11-22T07:00:15Z",
  "expiresAt": "2024-11-22T07:10:15Z",
  "state": "state_a4b5c6d7e8f9g0h1i2j3",
  "nonce": "nonce_c3d4e5f6g7h8i9j0k1l2",
  "authenticationMethod": {
    "@type": "AuthenticationMethod",
    "name": "social-google"
  },
  "consentDecision": {
    "approvedScopes": [
      "openid",
      "email"
    ],
    "deniedScopes": [
      "profile"
    ],
    "rememberConsent": false
  },
  "metadata": {
    "ipAddress": "198.18.0.45",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
  }
}