Tokens API — Mutations

Create, revoke, and manage scopes on API tokens. Also supports machine-to-machine (M2M) authentication via client credentials.

Endpoint

POSThttps://api.udacity.com/api/public/api/v1/tokens/graphql

`createToken`

Create a new API token.

Authentication: Requires logged-in user (JWT).

descriptionString!Required

A description for the token.

expiresAtTime

Optional expiration date (RFC 3339 format).

Returns NewToken. The unredactedToken value is only returned once at creation.

Signature

type Mutation {
  createToken(input: CreateTokenInput!): NewToken!
}

Mutation

mutation CreateToken($input: CreateTokenInput!) {
  createToken(input: $input) {
    unredactedToken
    token {
      id
      description
      createdAt
      expiresAt
    }
  }
}

Variables

{
  "input": {
    "description": "Production reporting token",
    "expiresAt": "2025-07-01T00:00:00Z"
  }
}

`revokeToken`

Revoke an existing API token. Only the token creator or staff can revoke.

Authentication: Requires logged-in user (JWT). Must be the token owner or staff.

tokenIdID!Required

The ID of the token to revoke.

Signature

type Mutation {
  revokeToken(tokenId: ID!): Boolean!
}

Mutation

mutation RevokeToken($tokenId: ID!) {
  revokeToken(tokenId: $tokenId)
}

Variables

{
  "tokenId": "token-001"
}

`addTokenScope`

Add an authorization scope to an existing token.

Authentication: Requires staff role.

tokenIdID!Required

The token to add the scope to.

scopeTypeScopeType!Required

The type of scope.

scopeKeyID!Required

The scope key (e.g., company ID).

Signature

type Mutation {
  addTokenScope(input: AddTokenScopeInput!): Token!
}

Mutation

mutation AddScope($input: AddTokenScopeInput!) {
  addTokenScope(input: $input) {
    id
    scopes {
      id
      scopeType
      scopeKey
    }
  }
}

Variables

{
  "input": {
    "tokenId": "token-001",
    "scopeType": "COMPANY",
    "scopeKey": "4821"
  }
}

`removeTokenScope`

Remove a scope from an existing token.

Authentication: Requires staff role.

tokenIdID!Required

The token ID.

scopeIdID!Required

The scope ID to remove.

Signature

type Mutation {
  removeTokenScope(tokenId: ID!, scopeId: ID!): Token!
}

Mutation

mutation RemoveScope($tokenId: ID!, $scopeId: ID!) {
  removeTokenScope(tokenId: $tokenId, scopeId: $scopeId) {
    id
    scopes {
      id
      scopeType
      scopeKey
    }
  }
}

`createClientCredential`

Create a new client credential (client ID + secret) bound to one or more companies. Used for machine-to-machine (M2M) authentication — the credential can later be exchanged for short-lived API tokens via generateToken without requiring a user JWT.

Authentication: Requires logged-in user (JWT). Non-staff users must be an active learner in every specified company.

companyIds[ID!]!Required

The company IDs to bind this credential to.

revokeExistingBoolean

When true, revokes all existing active credentials that overlap with any of the specified company IDs before creating the new one. Defaults to false.

Returns NewClientCredential. The clientSecret is only returned once — store it securely.

Signature

type Mutation {
  createClientCredential(input: CreateClientCredentialInput!): NewClientCredential!
}

Mutation

mutation CreateClientCredential($input: CreateClientCredentialInput!) {
  createClientCredential(input: $input) {
    clientId
    clientSecret
    credential {
      id
      companyIds
      createdAt
    }
  }
}

Variables

{
  "input": {
    "companyIds": ["4821"],
    "revokeExisting": true
  }
}

`revokeClientCredential`

Revoke a client credential by its ID. Any tokens previously generated with this credential will continue to work until they expire.

Authentication: Requires logged-in user (JWT).

credentialIdID!Required

The ID of the credential to revoke.

Signature

type Mutation {
  revokeClientCredential(credentialId: ID!): Boolean!
}

Mutation

mutation RevokeClientCredential($credentialId: ID!) {
  revokeClientCredential(credentialId: $credentialId)
}

Variables

{
  "credentialId": "credential-001"
}

`generateToken`

Exchange a client ID and secret for a short-lived API token with a COMPANY scope automatically attached. This is the core machine-to-machine (M2M) flow — no user JWT required.

When a credential is bound to multiple companies, companyId is required to specify which company the token should be scoped to.

Authentication: No JWT required. The client credentials serve as the authentication mechanism.

clientIdID!Required

The client ID of the credential.

clientSecretString!Required

The client secret of the credential.

companyIdID

The company to generate a COMPANY-scoped token for. Required when the credential is bound to multiple companies; omit to default to the credential’s only company.

Returns NewToken with unredactedToken, expiresIn, and primaryScope populated.

Signature

type Mutation {
  generateToken(input: GenerateTokenInput!): NewToken!
}

Mutation

mutation GenerateToken($input: GenerateTokenInput!) {
  generateToken(input: $input) {
    unredactedToken
    expiresIn
    primaryScope {
      scopeType
      scopeKey
    }
  }
}

Variables

{
  "input": {
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "companyId": "4821"
  }
}