Create sessions
/sessionsStart or complete a sign-in. The response says which step you are on. The credential is optional, see below.
SessCmdChangePasswordSessCmdDiscoverSessCmdSendCustomerOtpSessCmdSendEmailLinkSessCmdSendOtpSessCmdSendPasswordResetSessCmdSignInCustomerSessCmdSignInCustomerOtpSessCmdSignInEmailLinkSessCmdSignInFederatedSessCmdSignInOtpSessCmdSignInPasswordSessCmdSignInPasswordResetSessCmdStartFederatedPermissions
sessions:createRequires the `create` action on `sessions` for the supplied runtime context
Request body
This body is a typed union. Pick a variant to see its fields and a matching example.
typetype = "SessCmdChangePassword"currentPasswordstringrequirednewPasswordstringrequiredcurl -X POST https://api.tst.au.apgpay.dev/sessions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "SessCmdChangePassword",
"currentPassword": "string",
"newPassword": "string"
}'Responses
The response is a tagged shape: type is always "SessCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.
typetype = "SessCreateRspAttributes"The resource that was created.
typeA session that has been authenticated, and what it can do.
userIdUserIdrequiredIdentifier of a user.
Example user_9f2Kd8QpLzXw
displayNamestringrequiredThe user's name, as the platform holds it.
Example Ada Lovelace
The domain this session is acting in. A session carries exactly one at a time.
typeenumrequiredSessDomainAttributestypeAn unauthenticated caller, restricted to what the wrapped domain permits.
typeOne customer.
customerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
A delegate acting for one customer. Scoped by both, because a delegate can act for several.
delegateIdCustdIdrequiredIdentifier of a customer delegate.
Example custd_9f2Kd8QpLzXw
forCustomerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
loanAccessarray of LoanIdLoans this delegate may act on for this customer; absent = unrestricted.
Example loan_9f2Kd8QpLzXw
One enterprise.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
One marketplace.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
One merchant.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
The whole platform. Held by platform operators.
The whole platform. Held by platform operators.
One customer.
customerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
A delegate acting for one customer. Scoped by both, because a delegate can act for several.
delegateIdCustdIdrequiredIdentifier of a customer delegate.
Example custd_9f2Kd8QpLzXw
forCustomerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
loanAccessarray of LoanIdLoans this delegate may act on for this customer; absent = unrestricted.
Example loan_9f2Kd8QpLzXw
One enterprise.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
One marketplace.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
One merchant.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
A domain that no longer resolves, the party it named is gone.
A domain that no longer resolves, the party it named is gone.
The whole platform. Held by platform operators.
The whole platform. Held by platform operators.
descriptionstringrequiredWhat the platform calls this domain, the merchant's or marketplace's name. This is how a user tells two apart.
roleIdsarray of stringThe roles the session holds in that domain. Why it can do what it can.
Example role_9f2Kd8QpLzXw
What it can actually do, the roles' grants, expanded.
typeenumrequiredSessCapabilityAttributesresourcePermissionResourcerequiredThe resource these capabilities are over.
BlockedCardCustomerDelegatesDisputesEnterprisesFxRatesLoanFacilitiesLoanProductsLoanTransactionsLoanMasterAgreementsLoans+52 moreShow fewer
LoanStatements, CreditCards, Files, Queues, Reports, Simulations, Marketplaces, MarketplaceUsers, Merchants, MerchantCustomers, Orders, CustomerPaymentSources, TemporaryPaymentSources, PaymentTokens, PayPlanOffers, PayCards, PayPlans, PayToAgreements, Refunds, MerchantServiceTokens, MarketplaceServiceTokens, EnterpriseServiceTokens, SourceVerifications, SystemJournals, SystemJournalEntries, SystemLedgers, SystemLedgerEntries, Transactions, IssuerTransactions, IssuerTransactionDiscrepancies, WebhookMerchantSubscriptions, WebhookMarketplaceSubscriptions, WebhookSubscriptions, Sessions, ServiceTokens, ReferenceData, Users, Roles, OidcIdps, ReportsAcquiring, ReportsLending, ReportsIssuing, ReportsCustomers, ReportsOperations, ReportsOversight, Organisations, Persons, Suppliers, Rules, MerchantStatementPasswords, MerchantTravelData, Unknown
actionsarray of PermissionActionThe actions the session holder may take on the resource.
CreateReadUpdateDeleteReadPiiReadAllCreateBillingPaymentSourceReadBillingPaymentSourceUpdateBillingPaymentSourceDeleteBillingPaymentSource+38 moreShow fewer
CreateFinancials, ReadFinancials, SearchFinancials, UpdateFinancials, DeleteFinancials, CreateKyb, ReadKyb, UpdateKyb, DeleteKyb, CreatePaymentProfiles, ReadPaymentProfiles, UpdatePaymentProfiles, DeletePaymentProfiles, CreatePermissions, ReadPermissions, UpdatePermissions, DeletePermissions, CreateState, ReadState, UpdateState, DeleteState, Activate, ActivatePaymentProfile, Apply, CreateUatp, Impersonate, Link, Orchestrate, Pay, Search, Simulate, SpecifySurcharge, Transfer, Upsert, UpsertMinimal, UpsertPlugin, Verify, Unknown
rbacHashstringrequiredA fingerprint of the permissions behind this session. It changes when the user's roles do, so a stale one means re-read.
directDebitAccountKindsarray of PsrcBankAccountKindThe kinds of bank account the platform can take a direct debit from. Offer only these PsrcBankAccount kinds when storing a direct debit source: any other can be stored, but no debit can be taken from it.
AuNzSgHkHkUsdUnknownexpiresAtstring (date-time)requiredWhen the session stops working.
Example 2026-08-19T04:21:07Z
Contact-verification codes are on their way. Echo these timestamps back exactly, they are signed into the proof tokens.
emailSentAtstring (date-time)Absent when no code went to an email address.
Example 2026-08-19T04:21:07Z
phoneSentAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
The contact details are verified. Proof tokens, plus a bearer for the customer.
emailTokenstringrequiredProof the email address was verified. Empty where no email code was answered.
Example ada@example.com
phoneTokenstringrequiredProof the phone number was verified.
Example +61400000000
signInTokenstringrequiredA bearer for the customer's session, present it directly. It lasts its hour and has no refresh token.
Example tok_9f2Kd8QpLzXwR4mN
One-time codes are on their way to the customer.
phoneNumberLast4stringLast four digits of the phone number a code went to. Absent when no phone number was on record, so only the email address was used.
Example 4242
A session that was just minted, and the credentials that carry it.
tokenstringrequiredThe bearer for this session. Treat it as a credential, and present it as Authorization: Bearer.
Example tok_9f2Kd8QpLzXwR4mN
refreshTokenstringrequiredRedeem this for a new bearer. Rotated on every use, keep the newest.
Example tok_9f2Kd8QpLzXwR4mN
expiresAtstring (date-time)requiredWhen the bearer stops working.
Example 2026-08-19T04:21:07Z
The domain this session is acting in.
typeenumrequiredSessDomainAttributestypeAn unauthenticated caller, restricted to what the wrapped domain permits.
typeOne customer.
customerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
A delegate acting for one customer. Scoped by both, because a delegate can act for several.
delegateIdCustdIdrequiredIdentifier of a customer delegate.
Example custd_9f2Kd8QpLzXw
forCustomerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
loanAccessarray of LoanIdLoans this delegate may act on for this customer; absent = unrestricted.
Example loan_9f2Kd8QpLzXw
One enterprise.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
One marketplace.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
One merchant.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
The whole platform. Held by platform operators.
The whole platform. Held by platform operators.
One customer.
customerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
A delegate acting for one customer. Scoped by both, because a delegate can act for several.
delegateIdCustdIdrequiredIdentifier of a customer delegate.
Example custd_9f2Kd8QpLzXw
forCustomerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
loanAccessarray of LoanIdLoans this delegate may act on for this customer; absent = unrestricted.
Example loan_9f2Kd8QpLzXw
One enterprise.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
One marketplace.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
One merchant.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
A domain that no longer resolves, the party it named is gone.
A domain that no longer resolves, the party it named is gone.
The whole platform. Held by platform operators.
The whole platform. Held by platform operators.
descriptionstringrequiredWhat the platform calls this domain, the merchant's or marketplace's name. This is how a user tells two apart.
Every domain the user holds, in the platform's precedence order. Switch between them with a PATCH.
typeenumrequiredSessDomainAttributestypeAn unauthenticated caller, restricted to what the wrapped domain permits.
typeOne customer.
customerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
A delegate acting for one customer. Scoped by both, because a delegate can act for several.
delegateIdCustdIdrequiredIdentifier of a customer delegate.
Example custd_9f2Kd8QpLzXw
forCustomerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
loanAccessarray of LoanIdLoans this delegate may act on for this customer; absent = unrestricted.
Example loan_9f2Kd8QpLzXw
One enterprise.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
One marketplace.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
One merchant.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
The whole platform. Held by platform operators.
The whole platform. Held by platform operators.
One customer.
customerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
A delegate acting for one customer. Scoped by both, because a delegate can act for several.
delegateIdCustdIdrequiredIdentifier of a customer delegate.
Example custd_9f2Kd8QpLzXw
forCustomerIdCustIdrequiredIdentifier of a customer.
Example cust_9f2Kd8QpLzXw
loanAccessarray of LoanIdLoans this delegate may act on for this customer; absent = unrestricted.
Example loan_9f2Kd8QpLzXw
One enterprise.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
One marketplace.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
One merchant.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
A domain that no longer resolves, the party it named is gone.
A domain that no longer resolves, the party it named is gone.
The whole platform. Held by platform operators.
The whole platform. Held by platform operators.
descriptionstringrequiredWhat the platform calls this domain, the merchant's or marketplace's name. This is how a user tells two apart.
A link is on its way to the email address given.
purposeSessLinkPurposerequiredWhich link was sent, a sign-in link, or a set/reset-password link.
SignInPasswordResetUnknownHow the identified user signs in, and the handle to carry into the sign-in.
SessMethodBuiltIn for APG Pay's own credential store, SessMethodFederated for an external identity provider.
typeThe user signs in against APG Pay's own credential store.
methodsarray of SessBuiltInMethodEvery built-in method this user can sign in with, in no particular order. Offer a chooser when there is more than one. Never empty, an identifier the platform does not know answers [Password], which is the same answer a real password user gets.
PasswordEmailLinkOtpUnknownThe user signs in at an external OpenID Connect identity provider.
idpDisplayNamestringrequiredWhat to call the provider on the hand-off interstitial. This is why the method is a union rather than an enum value.
Example Ada Lovelace
selectedDomainHandlestringrequiredOpaque handle for the permission domain the method was resolved from. Present it unchanged on the sign-in arm. It carries no readable information and grants nothing on its own. Valid for one hour.
A one-time code is on its way. Quote challengeId when submitting it.
challengeIdSessOtpChallengeIdrequiredHandle naming the challenge. Present it with the code on SessCmdSignInOtp. Grants nothing on its own.
Example lotp_9f2Kd8QpLzXw
channelSessOtpChannelrequiredWhich contact detail the code went to, so the prompt can say which one to check.
EmailPhoneUnknownThe password was changed, and every refresh token you hold is revoked: your bearer works until it expires, and then you sign in again.
The password was changed, and every refresh token you hold is revoked: your bearer works until it expires, and then you sign in again.
A B2B prospect with no existing delegate. Carry this token through the onboarding flow.
b2bProspectTokenstringrequiredCarry through the B2B onboarding flow. Treat as a credential.
Example tok_9f2Kd8QpLzXwR4mN
The session cannot move to that domain without authenticating again.
What to authenticate with. Present the current bearer as sessionToken so the new session carries both methods.
typeThe user signs in against APG Pay's own credential store.
methodsarray of SessBuiltInMethodEvery built-in method this user can sign in with, in no particular order. Offer a chooser when there is more than one. Never empty, an identifier the platform does not know answers [Password], which is the same answer a real password user gets.
PasswordEmailLinkOtpUnknownThe user signs in at an external OpenID Connect identity provider.
idpDisplayNamestringrequiredWhat to call the provider on the hand-off interstitial. This is why the method is a union rather than an enum value.
Example Ada Lovelace
Navigate the browser to the identity provider's authorisation URL.
{
"type": "SessCreateRspAttributes",
"created": {
"type": "SessViewAuthenticated",
"userId": "user_9f2Kd8QpLzXw",
"displayName": "Ada Lovelace",
"activeDomain": {
"type": "SessDomainAttributes",
"domain": {
"type": "UserDomainAnonymous",
"restrictedTo": {
"type": "UserDomainCustomer",
"customerId": "cust_9f2Kd8QpLzXw"
}
},
"description": "string"
},
"roleIds": [
"role_9f2Kd8QpLzXw"
],
"capabilities": [
{
"type": "SessCapabilityAttributes",
"resource": "BlockedCard",
"actions": [
"Create"
]
}
],
"rbacHash": "string",
"directDebitAccountKinds": [
"Au"
],
"expiresAt": "2026-08-19T04:21:07Z"
}
}Error responses
statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}