open_payments/grants

Types

Information about the client instance that the auth server shows to the resource owner during interaction. Every field is optional. It is supplied by the client and not checked by the auth server. If an interactive grant request leaves it out, the auth server gets it from the client’s wallet address.

pub type ClientDisplay {
  ClientDisplay(
    name: option.Option(String),
    uri: option.Option(String),
    logo_uri: option.Option(String),
  )
}

Constructors

How the client making the grant request identifies itself: either directly with its public key (jwk), or via a wallet address whose keys the auth server can look up.

pub type ClientType {
  ClientDirectedIdentity(
    jwk: types.Key,
    display: option.Option(ClientDisplay),
  )
  ClientWalletAddressObject(
    wallet_address: String,
    display: option.Option(ClientDisplay),
  )
  ClientWalletAddressString(wallet_address: String)
}

Constructors

  • ClientDirectedIdentity(
      jwk: types.Key,
      display: option.Option(ClientDisplay),
    )

    Sent as {"jwk": ...}. Only usable for non-interactive grants.

  • ClientWalletAddressObject(
      wallet_address: String,
      display: option.Option(ClientDisplay),
    )

    Sent as {"walletAddress": ...}.

  • ClientWalletAddressString(wallet_address: String)

    Sent as a bare wallet address string. Deprecated by the Open Payments spec in favour of ClientWalletAddressObject; only use it for auth servers that don’t yet accept the object form.

The result of continuing a pending grant. access_token is present once the grant has been approved; subject is present once the requested subject information has been provided.

pub type ContinuationResponse {
  ContinuationResponse(
    access_token: option.Option(types.AccessTokenResponse),
    subject: option.Option(Subject),
    continue: ContinueResponse,
  )
}

Constructors

The access token used to continue a pending grant.

pub type ContinueAccessToken {
  ContinueAccessToken(value: String)
}

Constructors

  • ContinueAccessToken(value: String)

Where and how to continue a grant, and how long to wait before polling again. wait is in seconds.

pub type ContinueResponse {
  ContinueResponse(
    access_token: ContinueAccessToken,
    uri: String,
    wait: option.Option(Int),
  )
}

Constructors

How the client is notified once the user has completed interaction with the auth server, as requested in a grant’s interact options.

pub type Finish {
  Finish(method: FinishMethod, uri: String, nonce: String)
}

Constructors

How the client is notified once the user has completed interaction. Currently the Open Payments spec only defines "redirect".

pub type FinishMethod {
  FinishRedirect
}

Constructors

  • FinishRedirect

The options for a grant request. access may list up to three unique access items (e.g. incoming-payment and quote) to request them all in a single grant, each with unique actions, or be left as [] for a subject-only request; leaving both access and subject empty makes request return a ValidationError. client_type defaults to identifying the client by its own wallet address (ClientWalletAddressObject, sent as {"walletAddress": ...}) when left as None; pass Some(ClientDirectedIdentity(key, None)) to identify the client by its public key instead, which is only allowed without interact: request returns a ValidationError otherwise. subject requests information about a subject (e.g. to confirm wallet address ownership) rather than, or alongside, an access token. It is sent as the single sub_ids entry the spec allows, and requires interact to be set: request returns a ValidationError otherwise. See https://openpayments.dev/apis/auth-server/operations/post-request/

pub type GrantOptions {
  GrantOptions(
    auth_server_url: String,
    access: List(types.Access),
    interact: option.Option(Interact),
    client_type: option.Option(ClientType),
    subject: option.Option(SubjectId),
  )
}

Constructors

The result of a grant request. A grant is either pending client interaction (PendingGrant) or has already been approved (Grant). See https://openpayments.dev/apis/auth-server/operations/post-request/

pub type GrantResponse {
  PendingGrant(
    interact: InteractResponse,
    continue: ContinueResponse,
  )
  Grant(
    access_token: types.AccessTokenResponse,
    continue: ContinueResponse,
  )
}

Constructors

The interaction methods to request for a grant, and optionally how the client should be notified when interaction finishes.

pub type Interact {
  Interact(start: List(StartMode), finish: option.Option(Finish))
}

Constructors

Where to redirect the user to interact with the auth server, and how the client will be notified once interaction finishes.

pub type InteractResponse {
  InteractResponse(
    redirect: String,
    finish: option.Option(String),
  )
}

Constructors

  • InteractResponse(redirect: String, finish: option.Option(String))

How the client can start an interaction with the user. Currently the Open Payments spec only defines "redirect".

pub type StartMode {
  StartRedirect
}

Constructors

  • StartRedirect

The subject information returned on the continuation response once interaction completes. A grant request names its subject with a single SubjectId instead (see GrantOptions).

pub type Subject {
  Subject(sub_ids: List(SubjectId))
}

Constructors

A single identifier for the subject the client is requesting information about.

pub type SubjectId {
  SubjectId(id: String, format: SubjectIdFormat)
}

Constructors

Currently the Open Payments spec only defines "uri".

pub type SubjectIdFormat {
  SubjectIdFormatUri
}

Constructors

  • SubjectIdFormatUri

Values

pub fn cancel(
  client: client.Client,
  response: ContinueResponse,
) -> Result(Nil, error.OpenPaymentsError)

Cancels a pending grant request, invalidating its continuation so it can no longer be used to continue or retrieve the grant. See https://openpayments.dev/apis/auth-server/operations/delete-continue/

pub fn continue(
  client: client.Client,
  response: ContinueResponse,
  interact_ref: option.Option(String),
) -> Result(ContinuationResponse, error.OpenPaymentsError)

Continues a pending grant. Pass the interact_ref received once the user has completed interaction, or None to poll the grant (e.g. after the wait period), in which case the request is sent without a body. See https://openpayments.dev/apis/auth-server/operations/post-continue/

pub fn is_interactive_grant(grant: GrantResponse) -> Bool

Returns True if the grant requires the user to complete an interaction before it can be used.

pub fn request(
  client: client.Client,
  options: GrantOptions,
) -> Result(GrantResponse, error.OpenPaymentsError)

Requests a grant from the auth server for the given access. Pass more than one Access in options.access to request them all under a single grant, rather than requesting each with its own grant. Leave access as [] for a subject-only request (see options.subject). See https://openpayments.dev/apis/auth-server/operations/post-request/

✨ Search Document