open_payments - v1.1.0

open_payments/grants

Types

AccessTokenBodyProperty

</>

Wraps the access requested for the token issued by a grant.

pub type AccessTokenBodyProperty {
  AccessTokenBodyProperty(access: List(types.Access))
}

Constructors

Body

</>

The request body sent to the auth server to request a grant.

pub type Body {
  Body(
    access_token: option.Option(AccessTokenBodyProperty),
    client: ClientType,
    interact: option.Option(Interact),
    subject: option.Option(Subject),
  )
}

Constructors

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

Constructors 

  • ClientDirectedIdentity(jwk: types.Key)
  • ClientWalletAddressObject(wallet_address: String)

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: String, uri: String, nonce: String)
}

Constructors 

  • Finish(method: String, uri: String, nonce: String)

GrantOptions

</>

The options for a grant request. access may list more than one access kind (e.g. incoming-payment and quote) to request them all in a single grant, or be left as [] for a subject-only request. client_type defaults to identifying the client by its own wallet address (ClientWalletAddressObject) when left as None; pass Some(ClientDirectedIdentity(key)) to identify the client by its public key instead. subject requests information about a subject (e.g. to confirm wallet address ownership) rather than, or alongside, an access token; the auth server requires interact to be set whenever subject is used. 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),
    address: String,
    client_type: option.Option(ClientType),
    subject: option.Option(Subject),
  )
}

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(String), 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))

Subject

</>

The subject a client is requesting information about (e.g. to confirm wallet address ownership), sent as part of a grant request and returned on the continuation response once interaction completes. Exactly one sub_ids entry may be sent, per the Open Payments spec.

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: String,
) -> Result(ContinuationResponse, error.OpenPaymentsError)

Continues a pending grant after the user has completed interaction. 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