ServiceTokenClaims identity.service-token-claims@1

Generated at from openvibe-contracts v0.33.0 and openvibe-sdk v0.5.0.

Version
1.2.0
Owner
network
Visibility
public
Status
active
Compatibility
backward
Decision
ADR-003
Schema
https://openvibe.network/contracts/identity/service-token-claims.v1.json

Claims of a short-lived RS256 client-credentials token issued by OpenVibe.Network to a service or app principal. Replaces X-Internal-Key. App tokens (actor_type app) also carry project_id and env; receivers refuse env=sandbox unless they opted in.

Fields

FieldTypeRequiredDescriptionConstraints
issstringyesIssuer; https://openvibe.network in production. Receivers pass the issuer they expect to verifyServiceToken().
  • format uri
substringyes
  • pattern ^(svc:[a-z][a-z0-9-]{1,39}|app:app_[0-9A-HJKMNP-TV-Z]{26}|mod:mod_[0-9A-HJKMNP-TV-Z]{26})$
actor_typeenumyes
  • one of "service", "app", "mod"
audarray of stringyes
  • minItems 1
  • items: pattern ^[a-z0-9.-]+$
caparray of stringyesGranted capability ids; a trailing .* grants a family.
  • items: pattern ^[a-z][a-z0-9_]*(\.[a-z0-9_*]+)+$
nsarray of stringNamespace constraints, e.g. live.* or mod.example.*
iatintegeryes
expintegeryes
jtistringyes
  • minLength 8
project_idstringDeveloper project of an app principal (ADR-014). Services key tenancy by it. Absent on first-party service tokens.
  • pattern ^prj_[0-9A-HJKMNP-TV-Z]{26}$
envenumEnvironment of an app principal. A receiver MUST refuse env=sandbox (401 token.sandbox_refused) unless it opted in to sandbox tokens. Absent on first-party service tokens, which are production.
  • one of "sandbox", "production"
on_behalf_ofstringThe person who authorized an app through the authorization-code flow. Absent on client_credentials tokens.
  • pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: app-sandbox
{
  "iss": "https://openvibe.network",
  "sub": "app:app_01J0000000000000000000000Z",
  "actor_type": "app",
  "aud": [
    "openvibe.media"
  ],
  "cap": [
    "media.object.upload",
    "media.object.read"
  ],
  "ns": [
    "live.*"
  ],
  "iat": 1790000000,
  "exp": 1790000300,
  "jti": "tok_abcdef12",
  "project_id": "prj_01J0000000000000000000000Z",
  "env": "sandbox",
  "on_behalf_of": "usr_01J0000000000000000000000Z"
}
Valid: live-to-media
{
  "iss": "https://openvibe.network",
  "sub": "svc:live",
  "actor_type": "service",
  "aud": [
    "openvibe.media"
  ],
  "cap": [
    "media.object.upload",
    "media.object.read"
  ],
  "ns": [
    "live.*"
  ],
  "iat": 1790000000,
  "exp": 1790000300,
  "jti": "tok_abcdef12"
}
Rejected: app-without-project
{
  "iss": "https://openvibe.network",
  "sub": "app:app_01J0000000000000000000000Z",
  "actor_type": "app",
  "aud": [
    "openvibe.media"
  ],
  "cap": [
    "media.object.upload",
    "media.object.read"
  ],
  "ns": [
    "live.*"
  ],
  "iat": 1790000000,
  "exp": 1790000300,
  "jti": "tok_abcdef12",
  "env": "sandbox",
  "on_behalf_of": "usr_01J0000000000000000000000Z"
}
Rejected: no-audience
{
  "iss": "https://openvibe.network",
  "sub": "svc:live",
  "actor_type": "service",
  "aud": [],
  "cap": [],
  "iat": 1,
  "exp": 2,
  "jti": "tok_abcdef12"
}
Rejected: non-uri-issuer
{
  "iss": "openvibe network",
  "sub": "svc:live",
  "actor_type": "service",
  "aud": [
    "openvibe.media"
  ],
  "cap": [],
  "iat": 1,
  "exp": 2,
  "jti": "tok_abcdef12"
}
Rejected: user-subject
{
  "iss": "https://openvibe.network",
  "sub": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "actor_type": "service",
  "aud": [
    "openvibe.media"
  ],
  "cap": [],
  "iat": 1,
  "exp": 2,
  "jti": "tok_abcdef12"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('identity.service-token-claims@1', value);   // { valid, errors: [{ path, message }] }