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
-
ClientDisplay( name: option.Option(String), uri: option.Option(String), logo_uri: option.Option(String), )
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
-
ContinuationResponse( access_token: option.Option(types.AccessTokenResponse), subject: option.Option(Subject), continue: ContinueResponse, )
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.
pub type ContinueResponse {
ContinueResponse(
access_token: ContinueAccessToken,
uri: String,
wait: option.Option(Int),
)
}
Constructors
-
ContinueResponse( access_token: ContinueAccessToken, uri: String, wait: option.Option(Int), )
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
-
Finish(method: FinishMethod, uri: String, nonce: String)
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)) 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
-
GrantOptions( auth_server_url: String, access: List(types.Access), interact: option.Option(Interact), client_type: option.Option(ClientType), subject: option.Option(SubjectId), )
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
-
PendingGrant( interact: InteractResponse, continue: ContinueResponse, ) -
Grant( access_token: types.AccessTokenResponse, continue: ContinueResponse, )
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
-
Interact(start: List(StartMode), finish: option.Option(Finish))
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
A single identifier for the subject the client is requesting information about.
pub type SubjectId {
SubjectId(id: String, format: SubjectIdFormat)
}
Constructors
-
SubjectId(id: String, format: SubjectIdFormat)
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/