open_payments - v2.0.0

open_payments/grants

Types

ClientType

</>

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)
  ClientWalletAddressObject(wallet_address: String)
  ClientWalletAddressString(wallet_address: String)
}

Constructors 

  • ClientDirectedIdentity(jwk: types.Key)

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

  • ClientWalletAddressObject(wallet_address: String)

    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.

ContinuationResponse

</>

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

ContinueAccessToken

</>

The access token used to continue a pending grant.

pub type ContinueAccessToken {
  ContinueAccessToken(value: String)
}

Constructors 

  • ContinueAccessToken(value: String)

ContinueResponse

</>

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

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

Constructors

Finish

</>

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

FinishMethod

</>

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

GrantOptions

</>

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)) 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

GrantResponse

</>

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

Interact

</>

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

InteractResponse

</>

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))

StartMode

</>

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

pub type StartMode {
  StartRedirect
}

Constructors 

  • StartRedirect

Subject

</>

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

SubjectId

</>

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

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

Constructors

SubjectIdFormat

</>

Currently the Open Payments spec only defines "uri".

pub type SubjectIdFormat {
  SubjectIdFormatUri
}

Constructors 

  • SubjectIdFormatUri

Values

cancel

</> 
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/

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/

is_interactive_grant

</> 
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.

request

</> 
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