Credential transport
Use the API base address supplied for your integration. Examples use ${WALLKIT_API_BASE} for the scheme and host only; each example appends /api/v1/.... Do not append that prefix twice.
| Header | Type / requirement | When to use it |
|---|---|---|
resource | string; resource-scoped context | Resource public key selecting catalog, settings or access context. It is not a resource secret. Supply it for resource-scoped requests and ordinary user-session resolution. |
token | string; member context | Existing Wallkit user-session token for user operations. Send this custom header. Do not use an Authorization Bearer header. |
session | string; guest access/details context | Stable guest-session identifier when using guest access checks/details. Send without token for guest context. It can create a guest-session record. Not required for guest-readable catalog or settings. |
firebase-token | string; configured Firebase-enabled member context | Firebase ID token alongside a Wallkit token for Firebase-enabled member requests in the user namespace. Does not replace token. |
service-api-key | string; trusted server context for permitted actions | Existing resource-scoped service-account key alongside resource. Requires the exact route and account action grant; see server contexts. Not a member token or universal guest credential. |
Use the resource key and existing integration configuration supplied to you. These pages do not provision keys. Follow ordinary identity-to-access or the separate Firebase identity to establish member context. Do not send every client header to every operation: guest-readable catalog/settings need the resource key, whereas access evaluation needs an established member or guest context. Firebase handling differs between user-namespace and public catalog controllers; follow each operation’s instructions.
Member operations use the permitted user role or inherited permission and the operation’s required active/unlocked resource context. Guest, administrator and service-account actions have separate allowances; each reference states the permitted actor. A resource key, administrator credential or service key is not a universal replacement for a member token. Use the server context only for its permitted integration actions.
Each operation states its request encoding. Identity/profile writes normally use JSON, selected actions also accept form fields, and the photo example uses multipart. Catalog/access reads normally use headers, path segments and query parameters. Encode string path segments and query values. Keep resource secrets and service credentials out of browser code and copied examples; the ordinary OAuth code exchange requires trusted server handling of client_secret.
Keep credentials separate
| Credential | Purpose | Transport / exact definition |
|---|---|---|
| Wallkit session token | Establish member-session context; content permission is a separate decision. | Custom token header. See ordinary authentication fields or session projection, as selected by the operation. |
| Wallkit refresh value | Request new authentication parameters from an existing stored refresh record. | JSON/form refresh_token in ordinary refresh. Returned fields use the operation’s authentication projection. Ordinary password sign-in does not establish reuse of its returned refresh value. |
| Authorization code | Complete the configured trusted-server code exchange. | JSON code in OAuth exchange; not a member token. Its result uses the session projection, with operation-specific user/session merge order. |
| Firebase ID token | Identify the provider user in the configured resource/project. | firebase-token header for Wallkit exchange and applicable member calls. Firebase registration instead reads JSON firebase_id_token. Firebase sign-in returns it as firebase_token_id. |
| Firebase custom token | Start the configured Firebase client flow for an ID token. | custom-token returns firebase_custom_token. Use it with the configured provider client flow, not either member token header. |
| Receipt download link hashes | Retrieve the existing active stored receipt named by its supplied link. | Query user and file on receipt download; no member headers are required by that action. The correct pair is its credential; do not substitute user/transaction IDs or generate hashes in client code. |
| External auth token | Present identity to the existing external-auth integration. | Encoded path segment in external identity. That operation returns a Wallkit token and optionally a Firebase custom token; no full session projection or external-token lifetime guarantee. |
Token issuance, refresh, logout and revocation have operation-specific scope. A token_type:bearer response label does not change Wallkit’s custom header transport. Mail/reset acknowledgement does not establish a completed sign-in or password change.
If context fails
For resource_not_exists, check the resource public key and selected integration context. For auth_failed, supply the existing member or permitted guest context. For auth_access_fail, ask the administrator to check account activation and resource locks. Expired or compromised tokens need the existing session flow; replacing the resource key does not repair them. Common error recovery distinguishes these cases.
Next: choose the identity/access, Server-integrations (advanced) or 3rd party integration flows path for your job. The Getting started comparison helps select the actor before adapting a request.
Stripe integration administration
The three Stripe integration OAuth actions require admin access (partner inherits; root bypasses ACL), an active user and resource context. Ordinary member and service-account access do not grant these actions. Use an existing authorized admin credential in the custom token header and the selected resource public key in resource. For a session credential, use the session that resolves to that admin role in the selected resource; configured Firebase context can also apply.
The existing server resource-secret mechanism recognizes a 64-character SHA-256 HMAC of the resource public key using its resource secret as token, establishes admin API context and bypasses the user-namespace Firebase branch. Resource-secret handling belongs in trusted server code; these pages do not generate or provision credentials. Source initialization can create a synthetic admin user context when no configured API-access user resolves. Action-specific account ownership and callback correlation still need trusted integration handling.
| Value | Purpose / transport |
|---|---|
| Admin token | Existing authorized Wallkit admin context in token header; not a provider OAuth token. |
| Provider code | Existing Stripe callback authorization code in JSON code plus explicit mode on exchange. Not Wallkit member OAuth code. |
| Provider access/refresh token | Private integration connection credentials returned by exchange and attempted storage in selected resource settings; not member token/refresh inputs. |
| Provider customer/method ID or token/nonce | Provider-specific source setup inputs, as named by payment-source guide. Never substitute for local checkout source ID. |
| Local payment_method_id / user_card_id | Numeric Wallkit saved method/card ID read from sources/cards and supplied to member calculation/payment. Not a credential for admin OAuth. |
Integration exchange/deauthorization can change resource settings and conditionally clear guest content-view records. Read each action’s permissions, mode and partial-outcome guidance before changing a connection.
Supporting task credentials
In-depth integration tasks separates resource context, client reCAPTCHA tokens, email/file-hash pairs, application record IDs and provider tokens. Use each only for its selected operation. Account requests use a fixed deployment resource; a resource header does not select another request resource. Neither a request ID nor a payment acknowledgement proves member identity or content access.
Team, pass and sponsorship contexts
Use the exact task’s actor and credential, following the Group-memberships (teams) management, Event tickets activation and passes and sponsorship guides. Generic invite preview is resource-context; generic activation requires active invitee. Pass invitation preview and activation both require active recipient member context. Pass authorization exchange uses resource plus its existing pass token and returns a member token; a pass invite code is different. Sponsorship activation uses active member context plus slot code, with recipient-ID checks only if already bound. Codes/tokens are obtained through existing issuer flows, not provisioned by these docs.
Provider preferences and event contexts
Use existing Wallkit context for the exact operation, following 3rd party integration flows or Event tickets: submit a configured event. Provider keys/OAuth values stay in existing resource configuration; provider IDs are not authorization credentials.
| Operation group | Context | Identity difference |
|---|---|---|
| Mailchimp and Campaign Monitor member calls; HubSpot field read | Active member token plus resource | API configured-Firebase resolution can apply. Mailchimp target selection is global admin/root only; Campaign Monitor uses its exact role/relationship table. |
| Campaign Monitor public list discovery | Resource; guest permitted | No member token required; no API-specific Firebase user replacement. Stored configuration only. |
| ActiveCampaign | Active member token plus resource | Ordinary resolved session user; no API-specific Firebase replacement. Member-tag read/write also require an existing member-resource relationship. |
| Streak field read | Authorized token plus resource | Support is the lowest direct ACL grant; inherited roles and root can use it. Ordinary member access is insufficient. Active-user guards and API configured-Firebase context still apply. |
| Event submission | Resource; guest permitted; member token optional | Resolved identity/session supplies event context. Body IDs cannot select another member. API configured-Firebase resolution can apply; no active-member requirement in the event initializer. |
Mailchimp subscriber-info and ActiveCampaign member-tag GETs perform provider writes. Choosing a read path does not make it passive. See the exact operation before using it for inspection or recovery.
Server-integration contexts
Choose the actor for the Server-integrations (advanced). User activity is guest-readable with resource; it does not need a member token or service key. A service-account key does not automatically permit that guest action.
Attendees and external purchase records use the existing resource public key in resource plus a resource-scoped key in the custom service-api-key header. Keep that key in the trusted integration. The account must be active, not suspended and attached to an active service-account user; route ACL and full_access or exact account action grant are separate checks. Ordinary member/admin roles do not automatically grant these service actions; root bypass is separate. These pages do not issue keys or teach session provisioning.
External purchase controllers require active resolved user/resource context, including attached resource relationship lock/suspension checks when present. Target user lookup separately requires an existing relationship with this resource. Attendee initialization has no active-member guard, but still requires the enabled resource event system and the appropriate service account/route checks.
Service initialization can update sessions, expiry and request/audit counters even on GET. An invalid key can fall back to ordinary resolution rather than a dedicated invalid-key error. Use each action’s exact recovery table; changing a resource key cannot repair an account grant. Neither service authorization nor a stored transaction/activity/attendee result proves member content access.