Setup

Generated setup operations.

POST/v1/setupCreate the first ownersession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: setup_server
Max body: 64 KiB

Request body application/json · required

Example

{
  "authMode": "string",
  "interactive": true,
  "name": "Fargo",
  "password": "string",
  "requestId": "id_8h2k4q",
  "setupToken": "string",
  "username": "Fargo"
}

Schema

authModestring
interactiveboolean
namestringrequired
passwordstring
requestIdstring
setupTokenstringrequired
usernamestring

Responses

201Successapplication/json

Example

{
  "accessToken": "string",
  "authorizationHorizon": "string",
  "deviceId": "id_8h2k4q",
  "expiresAt": "2026-10-18T19:30:00Z",
  "installationId": "id_8h2k4q",
  "refreshToken": "string",
  "serverIdentity": {
    "fingerprint": "string",
    "publicKey": "string"
  },
  "sessionFamilyId": "id_8h2k4q",
  "tokenGeneration": "string",
  "variant": "session",
  "viewer": {
    "accountId": "id_8h2k4q",
    "authority": "string",
    "profileId": "id_8h2k4q",
    "role": "string",
    "serverId": "id_8h2k4q"
  }
}

Schema

accessTokenstringrequired
authorizationHorizonstringrequired
deviceIdstringrequired
expiresAtstringrequired
installationIdstringrequired
refreshTokenstring
serverIdentityobject
- fingerprintstringrequired
- publicKeystringrequired
sessionFamilyIdstringrequired
tokenGenerationstringrequired
variant"session"required
viewerobjectrequired
- accountIdstringrequired
- authoritystringrequired
- profileIdstringrequired
- rolestringrequired
- serverIdstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedinvalid_requestrate_limitedsetup_already_completesetup_in_progresssetup_portico_modeinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup" \
  -H "Content-Type: application/json" \
  -d '{"authMode":"string","interactive":true,"name":"Fargo","password":"string","requestId":"id_8h2k4q","setupToken":"string","username":"Fargo"}'

POST/v1/setup/abandonGo back to the start of an unapproved Portico Account setupsession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: post_setup_abandon
Max body: 4 KiB

Request body application/json · required

Example

{
  "requestId": "id_8h2k4q",
  "revision": "r12",
  "setupToken": "string"
}

Schema

requestIdstringrequired
revisionstringrequired
setupTokenstringrequired

Responses

200Successapplication/json

Example

{
  "retryAfterSeconds": 1,
  "setup": {
    "cancelling": true,
    "delivery": {
      "attempts": 0,
      "nextRetryAt": "2026-10-18T19:30:00Z",
      "since": "string",
      "slow": true
    },
    "expiresAt": "2026-10-18T19:30:00Z",
    "operation": {
      "localGeneration": "string",
      "operationId": "id_8h2k4q",
      "revision": "r12"
    },
    "outcome": "denied",
    "renewable": true,
    "requestId": "id_8h2k4q",
    "revision": "r12",
    "variant": "started"
  },
  "status": "string"
}

Schema

retryAfterSecondsinteger≥ 1
setupobject
- cancellingboolean
- deliveryobject
  - attemptsintegerrequired
  - nextRetryAtstring
  - sincestring
  - slowbooleanrequired
- expiresAtstring
- operationobject
  - localGenerationstringrequired
  - operationIdstringrequired
  - revisionstringrequired
- outcomestringone of "denied"
- renewableboolean
- requestIdstringrequired
- revisionstringrequired
- variant"started"required
statusstringrequired
Open: ready, in_progress or complete today. Read any other value as unknown.

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedinvalid_requestrate_limitedsetup_state_changedsetup_source_not_localinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/abandon" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"id_8h2k4q","revision":"r12","setupToken":"string"}'

POST/v1/setup/account/completeComplete account setup from its validated claimsession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: post_setup_account_complete
Max body: 16 KiB

Parameters

Name	In	Type	Description
`X-Portico-Installation-Id`	header	`string`

Request body application/json · required

Example

{
  "porticoIdentity": {
    "certificate": {
      "keyId": "id_8h2k4q",
      "notAfter": "2026-10-18T19:30:00Z",
      "notBefore": "2026-10-18T19:30:00Z",
      "publicKey": "string",
      "purpose": "string",
      "revision": 0,
      "revoked": [
        "string"
      ],
      "signature": "string"
    },
    "keyId": "id_8h2k4q",
    "payload": "string",
    "signature": "string"
  },
  "requestId": "id_8h2k4q",
  "setupToken": "string"
}

Schema

porticoIdentityobject | any | nullrequired
- certificateobject
  - keyIdstringrequired
  - notAfterstring (date-time)required
  - notBeforestring (date-time)required
  - publicKeystringrequired
  - purposestringrequired
  - revisionintegerrequired
  - revokedarray of stringrequired
  - signaturestringrequired
- keyIdstringrequired
- payloadstringrequired
- signaturestringrequired
requestIdstringrequired
setupTokenstringrequired

Responses

200Successapplication/json

Example

{
  "account": {
    "allowedLibraries": [
      "string"
    ],
    "disabled": true,
    "disabledAt": "2026-10-18T19:30:00Z",
    "disabledReason": "string",
    "hostedAccountId": "id_8h2k4q",
    "id": "id_8h2k4q",
    "primaryProfileId": "id_8h2k4q",
    "revision": 0,
    "role": "string",
    "username": "Fargo"
  },
  "authority": "string",
  "canManage": true,
  "capabilities": {
    "manageAccount": true,
    "managePeople": true,
    "manageServer": true,
    "manageSignIn": true
  },
  "challenge": {
    "expiresAt": "2026-10-18T19:30:00Z",
    "token": "string"
  },
  "custodyPending": true,
  "deviceId": "id_8h2k4q",
  "installationId": "id_8h2k4q",
  "managePinRequired": true,
  "passwordChangeRequired": true,
  "profiles": [
    {
      "allowedLibraries": [
        "string"
      ],
      "art": "string",
      "id": "id_8h2k4q",
      "name": "Fargo",
      "pinRequired": true,
      "pinRevision": 0,
      "position": 0,
      "primary": true,
      "revision": 0
    }
  ],
  "rememberProfiles": true,
  "resetFileOwnerSession": true,
  "serverId": "id_8h2k4q",
  "session": {
    "accessToken": "string",
    "authorizationHorizon": "string",
    "deviceId": "id_8h2k4q",
    "expiresAt": "2026-10-18T19:30:00Z",
    "installationId": "id_8h2k4q",
    "refreshToken": "string",
    "serverIdentity": {
      "fingerprint": "string",
      "publicKey": "string"
    },
    "sessionFamilyId": "id_8h2k4q",
    "tokenGeneration": "string",
    "viewer": {
      "accountId": "id_8h2k4q",
      "authority": "string",
      "profileId": "id_8h2k4q",
      "role": "string",
      "serverId": "id_8h2k4q"
    }
  },
  "twoStepSetupRequired": true
}

Schema

accountobjectrequired
- allowedLibrariesarray of stringrequired
- disabledbooleanrequired
- disabledAtstring
- disabledReasonstring
- hostedAccountIdstring
- idstringrequired
- primaryProfileIdstringrequired
- revisionintegerrequired
- rolestringrequired
- usernamestringrequired
authoritystringrequired
canManagebooleanrequired
capabilitiesobjectrequired
- manageAccountbooleanrequired
- managePeoplebooleanrequired
- manageServerbooleanrequired
- manageSignInbooleanrequired
challengeobject
- expiresAtstringrequired
- tokenstringrequired
custodyPendingboolean
deviceIdstring
installationIdstring
managePinRequiredboolean
passwordChangeRequiredboolean
profilesarray of objectrequired
- allowedLibrariesarray of stringrequired
- artstringrequired
- idstringrequired
- namestringrequired
- pinRequiredbooleanrequired
- pinRevisionintegerrequired
- positionintegerrequired
- primarybooleanrequired
- revisionintegerrequired
rememberProfilesbooleanrequired
resetFileOwnerSessionboolean
serverIdstringrequired
sessionobject
- accessTokenstringrequired
- authorizationHorizonstringrequired
- deviceIdstringrequired
- expiresAtstringrequired
- installationIdstringrequired
- refreshTokenstring
- serverIdentityobject
  - fingerprintstringrequired
  - publicKeystringrequired
- sessionFamilyIdstringrequired
- tokenGenerationstringrequired
- viewerobjectrequired
  - accountIdstringrequired
  - authoritystringrequired
  - profileIdstringrequired
  - rolestringrequired
  - serverIdstringrequired
twoStepSetupRequiredboolean

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedrate_limitedinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/account/complete" \
  -H "Content-Type: application/json" \
  -d '{
  "porticoIdentity": {
    "certificate": {
      "keyId": "id_8h2k4q",
      "notAfter": "2026-10-18T19:30:00Z",
      "notBefore": "2026-10-18T19:30:00Z",
      "publicKey": "string",
      "purpose": "string",
      "revision": 0,
      "revoked": [
        "string"
      ],
      "signature": "string"
    },
    "keyId": "id_8h2k4q",
    "payload": "string",
    "signature": "string"
  },
  "requestId": "id_8h2k4q",
  "setupToken": "string"
}'

POST/v1/setup/appStart first-run setup from an appsession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: start_app_setup
Max body: 4 KiB

Request body application/json · required

Example

{}

Schema

object

Responses

200Successapplication/json

Example

{
  "serverId": "id_8h2k4q",
  "setupToken": "string"
}

Schema

serverIdstringrequired
setupTokenstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedinvalid_requestrate_limitedsetup_already_completesetup_in_progresssetup_source_not_localinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/app" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/v1/setup/approvalAsk a Portico Account to approve this setupsession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: post_setup_approval
Max body: 20 KiB

Request body application/json · required

Example

{
  "setupStart": {
    "codeChallenge": "string",
    "installationId": "id_8h2k4q",
    "state": "string"
  }
}

Schema

setupStartobjectrequired
- codeChallengestringrequiredlength 43–43pattern ^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$
- installationIdstringrequiredlength 32–128pattern ^[A-Za-z0-9_-]+$
- statestringrequiredlength 43–43pattern ^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$

Responses

200Successapplication/json

Example

{
  "accountId": "id_8h2k4q",
  "actions": [
    "string"
  ],
  "approvalRequest": {
    "currentOwnerAccountId": "id_8h2k4q",
    "expectedRevision": "r12",
    "localGeneration": "string",
    "name": "Fargo",
    "operationId": "id_8h2k4q",
    "previousOwnerRole": "string",
    "publicKey": "string",
    "purpose": "string",
    "returnRegistrationId": "id_8h2k4q",
    "serverId": "id_8h2k4q"
  },
  "approvalRequired": true,
  "approvalUrl": "https://example.com/…",
  "claimCode": "string",
  "identity": {
    "localGeneration": "string",
    "serverId": "id_8h2k4q"
  },
  "installationAcknowledged": true,
  "operation": {
    "localGeneration": "string",
    "operationId": "id_8h2k4q",
    "revision": "r12"
  },
  "ownerContinuation": {
    "claim": {
      "payload": "string",
      "signature": "string"
    },
    "expiresAt": "2026-10-18T19:30:00Z",
    "phase": "string",
    "returnRegistration": {
      "id": "id_8h2k4q",
      "origin": "string"
    },
    "start": {
      "payload": "string",
      "signature": "string"
    },
    "transactionId": "id_8h2k4q"
  },
  "setupContinuation": {
    "claim": {
      "payload": "string",
      "signature": "string"
    },
    "expiresAt": "2026-10-18T19:30:00Z",
    "phase": "string",
    "start": {
      "payload": "string",
      "signature": "string"
    },
    "transactionId": "id_8h2k4q"
  },
  "state": "string"
}

Schema

accountIdstring
actionsarray of stringrequired
approvalRequestobject
- currentOwnerAccountIdstringrequired
- expectedRevisionstringrequired
- localGenerationstringrequired
- namestringrequired
- operationIdstringrequired
- previousOwnerRolestringrequired
- publicKeystringrequired
- purposestringrequired
- returnRegistrationIdstringrequired
- serverIdstringrequired
approvalRequiredbooleanrequired
approvalUrlstring
claimCodestring
identityobjectrequired
- localGenerationstringrequired
- serverIdstringrequired
installationAcknowledgedbooleanrequired
operationobject
- localGenerationstringrequired
- operationIdstringrequired
- revisionstringrequired
ownerContinuationobject
- claimobject
  - payloadstringrequired
  - signaturestringrequired
- expiresAtstringrequired
- phasestringrequired
- returnRegistrationobject
  - idstringrequired
  - originstringrequired
- startobject
  - payloadstringrequired
  - signaturestringrequired
- transactionIdstringrequired
setupContinuationobject
- claimobject
  - payloadstringrequired
  - signaturestringrequired
- expiresAtstringrequired
- phasestringrequired
- startobject
  - payloadstringrequired
  - signaturestringrequired
- transactionIdstringrequired
statestringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedinvalid_requestrate_limitedsetup_state_changedsetup_source_not_localinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/approval" \
  -H "Content-Type: application/json" \
  -d '{"setupStart":{"codeChallenge":"string","installationId":"id_8h2k4q","state":"string"}}'

POST/v1/setup/browserStart first-run setup from this originsession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: start_browser_setup
Max body: 4 KiB

Request body application/json · required

Example

{}

Schema

object

Responses

200Successapplication/json

Example

{
  "serverId": "id_8h2k4q",
  "setupToken": "string"
}

Schema

serverIdstringrequired
setupTokenstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedinvalid_requestrate_limitedsetup_already_completesetup_in_progresssetup_source_not_localinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/browser" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/v1/setup/resumeRun setup resumesession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: post_setup_resume
Max body: 64 KiB

Request body application/json · required

Example

{
  "requestId": "id_8h2k4q",
  "setupToken": "string"
}

Schema

requestIdstringrequired
setupTokenstringrequired

Responses

200Successapplication/json

Example

{
  "accessToken": "string",
  "authorizationHorizon": "string",
  "deviceId": "id_8h2k4q",
  "expiresAt": "2026-10-18T19:30:00Z",
  "installationId": "id_8h2k4q",
  "refreshToken": "string",
  "serverIdentity": {
    "fingerprint": "string",
    "publicKey": "string"
  },
  "sessionFamilyId": "id_8h2k4q",
  "tokenGeneration": "string",
  "variant": "session",
  "viewer": {
    "accountId": "id_8h2k4q",
    "authority": "string",
    "profileId": "id_8h2k4q",
    "role": "string",
    "serverId": "id_8h2k4q"
  }
}

Schema

accessTokenstringrequired
authorizationHorizonstringrequired
deviceIdstringrequired
expiresAtstringrequired
installationIdstringrequired
refreshTokenstring
serverIdentityobject
- fingerprintstringrequired
- publicKeystringrequired
sessionFamilyIdstringrequired
tokenGenerationstringrequired
variant"session"required
viewerobjectrequired
- accountIdstringrequired
- authoritystringrequired
- profileIdstringrequired
- rolestringrequired
- serverIdstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/resume" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"id_8h2k4q","setupToken":"string"}'

POST/v1/setup/retryTry again to apply the Portico Account approval of this setupsession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: post_setup_retry
Max body: 4 KiB

Request body application/json · required

Example

{
  "requestId": "id_8h2k4q",
  "revision": "r12",
  "setupToken": "string"
}

Schema

requestIdstringrequired
revisionstringrequired
setupTokenstringrequired

Responses

200Successapplication/json

Example

{
  "retryAfterSeconds": 1,
  "setup": {
    "cancelling": true,
    "delivery": {
      "attempts": 0,
      "nextRetryAt": "2026-10-18T19:30:00Z",
      "since": "string",
      "slow": true
    },
    "expiresAt": "2026-10-18T19:30:00Z",
    "operation": {
      "localGeneration": "string",
      "operationId": "id_8h2k4q",
      "revision": "r12"
    },
    "outcome": "denied",
    "renewable": true,
    "requestId": "id_8h2k4q",
    "revision": "r12",
    "variant": "started"
  },
  "status": "string"
}

Schema

retryAfterSecondsinteger≥ 1
setupobject
- cancellingboolean
- deliveryobject
  - attemptsintegerrequired
  - nextRetryAtstring
  - sincestring
  - slowbooleanrequired
- expiresAtstring
- operationobject
  - localGenerationstringrequired
  - operationIdstringrequired
  - revisionstringrequired
- outcomestringone of "denied"
- renewableboolean
- requestIdstringrequired
- revisionstringrequired
- variant"started"required
statusstringrequired
Open: ready, in_progress or complete today. Read any other value as unknown.

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedinvalid_requestrate_limitedsetup_state_changedsetup_source_not_localinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/setup/retry" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"id_8h2k4q","revision":"r12","setupToken":"string"}'

GET/v1/setup/stateRead first-run setup's statesession

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_setup_state

Responses

200Successapplication/json

Example

{
  "retryAfterSeconds": 1,
  "setup": {
    "cancelling": true,
    "delivery": {
      "attempts": 0,
      "nextRetryAt": "2026-10-18T19:30:00Z",
      "since": "string",
      "slow": true
    },
    "expiresAt": "2026-10-18T19:30:00Z",
    "operation": {
      "localGeneration": "string",
      "operationId": "id_8h2k4q",
      "revision": "r12"
    },
    "outcome": "denied",
    "renewable": true,
    "requestId": "id_8h2k4q",
    "revision": "r12",
    "variant": "started"
  },
  "status": "string"
}

Schema

retryAfterSecondsinteger≥ 1
setupobject
- cancellingboolean
- deliveryobject
  - attemptsintegerrequired
  - nextRetryAtstring
  - sincestring
  - slowbooleanrequired
- expiresAtstring
- operationobject
  - localGenerationstringrequired
  - operationIdstringrequired
  - revisionstringrequired
- outcomestringone of "denied"
- renewableboolean
- requestIdstringrequired
- revisionstringrequired
- variant"started"required
statusstringrequired
Open: ready, in_progress or complete today. Read any other value as unknown.

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesunauthorizedrate_limitedsetup_source_not_localinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/setup/state"