Partner Keys

Partner Keys let an approved partner create and manage natural-person residency applications over REST, on behalf of applicants, without leaving their own product. Each key (pk-...) is bound to one approved legal entity — a Partner Integration — and acts only within the scopes it was granted.

Base URL

Environment	Origin
Production	https://portal.eprospera.com
Staging	https://staging-portal.eprospera.com

All endpoint paths in this document are relative to that origin. The API ships from the same host as the consumer portal — there is no separate api.eprospera.com. Shared rules (errors, status codes, timestamps, rate limits, pagination) are documented once in Conventions — this page does not repeat them.

How Partners Get a Key

Partner Keys are admin-issued. There is no self-serve flow: a partner cannot request or generate a pk- key from the portal.

• eProspera staff create the Partner Integration (linking your approved legal entity to API access) and issue the key.
• The raw pk-... value and the base URL are delivered to you out-of-band (for example, over a secure channel agreed with your eProspera contact).
• The raw key is shown once at creation and is never recoverable afterward — only a hash is stored. Treat it like a password and store it securely.
• An integration can hold multiple keys (for example, one per environment), each with its own label and its own subset of scopes.
• Keys can be revoked at any time, and revocation takes effect immediately.

Partner Keys are distinct from the keys an individual e-resident manages themselves:

• Standard API keys (sk-) and Agent Keys (ak-) are self-issued by residents in the portal under Settings → Developer. See Agent Keys.
• Partner Keys (pk-) are issued by eProspera to an organization and act on residency applications the partner creates.

Authentication

Send the key as a bearer token on every request:

Authorization: Bearer pk-...

• The key is detected by its pk- prefix (vs. sk- standard and ak- agent keys).
• The token is SHA-256 hashed server-side; the raw value is never stored.
• Every endpoint is scope-checked. A request that is missing a required scope returns 403.
• A revoked key, or a key whose integration has been revoked, returns 401.

Scope Reference

A key only does what its scopes allow. eProspera selects the scopes when issuing the key.

Scope	Description
partner:person.application.read	List and read the natural-person residency applications this partner created
partner:person.application.create	Create a new natural-person residency application
partner:person.application.update	Update an in-progress (Draft) application
partner:person.application.pay	Create checkout sessions and apply voucher payments to an application's invoice
partner:person.application.submit	Submit an application for review
partner:person.aoc.sign	Submit the Agreement of Coexistence (AOC) signature via the API

Notes:

• Uploading proof of address requires the partner:person.application.create or partner:person.application.update scope.
• Identity verification is not a partner-API capability. The applicant completes identity verification inside the eProspera portal; submit requires an approved result from that portal flow.

Endpoints

Method	Path	Required scope
POST	/api/v1/partner/residency_applications	partner:person.application.create
GET	/api/v1/partner/residency_applications	partner:person.application.read
GET	/api/v1/partner/residency_applications/{id}	partner:person.application.read
PATCH	/api/v1/partner/residency_applications/{id}	partner:person.application.update
POST	/api/v1/partner/residency_applications/{id}/checkout_session	partner:person.application.pay
POST	/api/v1/partner/residency_applications/{id}/pay/voucher	partner:person.application.pay
POST	/api/v1/partner/residency_applications/{id}/signature	partner:person.aoc.sign
POST	/api/v1/partner/residency_applications/{id}/submit	partner:person.application.submit
POST	/api/v1/uploads/proof_of_address	create or update

A partner only ever sees its own applications — every query is filtered by the integration behind the authenticated key. Requesting an application that belongs to another partner returns 404 (not 403), so the existence of other partners' applications is never revealed.

Supported Residency Products

Applications can be created for these product codes:

• limited_e_resident
• e_resident
• resident_annual

Once the application's invoice is effectively paid, the residency product is locked and cannot be changed.

Application Lifecycle

A partner drives the residency application on behalf of an applicant:

1. Create the draft — POST /api/v1/partner/residency_applications with the applicant's data. This provisions (or reuses) the applicant's portal account by email and creates a Draft tied to that applicant.
2. Attach proof of address — either upload a file to POST /api/v1/uploads/proof_of_address and pass the returned URL into a PATCH, or submit a sworn statement inline via PATCH. The invoice is created or refreshed once proof of address exists.
3. Pay the invoice — create a hosted checkout session (/checkout_session) or apply a full-coverage voucher (/pay/voucher).
4. Complete the AOC signature — either call /signature after collecting the signature in your own UI, or send the applicant to the hosted signing page returned as nextSteps.signatureUrl.
5. Applicant completes identity verification in the eProspera portal — this step is not available via the partner API.
6. Submit — POST /api/v1/partner/residency_applications/{id}/submit. From there the existing review and approval flow takes over.

Submit succeeds only when all of these are true: proof of address is attached, the AOC signature is recorded, the invoice is paid, and an approved identity-verification result exists from the portal flow.

nextSteps Response Fields

Create, read, update, payment, signature, and submit responses include a nextSteps object computed from the draft's current state, so a client can tell what remains before submit:

Field	Meaning
signatureUrl	Hosted AOC signing page, returned while the draft is unsigned
proofOfAddressRequired	true until proof of address is attached
paymentRequired	true until the invoice is paid
verificationRequired	true until an approved identity-verification result exists
verificationInstructions	Guidance directing the applicant to verify in the eProspera portal
submitReady	true only when proof, signature, payment, and verification are all complete

Read responses also include an applicantPortalAccess block (email, hasLoggedIn, lastLogin, claimLinkSent, claimLinkSentAt) so the partner can tell whether the applicant has claimed their portal account.

Examples

Create a draft application:

curl -X POST https://portal.eprospera.com/api/v1/partner/residency_applications \
  -H "Authorization: Bearer pk-REDACTED" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "e_resident",
    "email": "applicant@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "dateOfBirth": "1990-12-10",
    "phoneNumber": "+50412345678",
    "countryOfBirth": "GB",
    "citizenships": ["GB"]
  }'

List the applications this partner has created:

curl https://portal.eprospera.com/api/v1/partner/residency_applications \
  -H "Authorization: Bearer pk-REDACTED"

If the key includes the required scope, the request succeeds. Otherwise the API returns 403.

Important Notes

• Provisioning is admin-only. Partners cannot self-serve a pk- key; eProspera issues it.
• Identity verification is portal-only. It cannot be initiated or completed through the partner API, and an approved result is required before submit.
• Every partner API action is audited — the key, the integration, the request, and the response are recorded.
• One active integration per legal entity. A revoked integration cannot be recreated for the same entity; contact eProspera if you need a fresh integration.
• Partner Keys cover the natural-person residency flow only. For consent-based legal-entity sharing use OAuth / OIDC; for resident-delegated automation use Agent Keys.