Auth

Generated auth operations.

GET/v1/auth/capabilitiesRead the server's available sign-in methodsopen

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

Responses

200Successapplication/json

Example

{
  "hostedAttach": true,
  "methods": [
    "string"
  ],
  "quickConnect": true,
  "selfRegistration": "string",
  "serverId": "id_8h2k4q",
  "serverName": "Fargo",
  "setupRequired": true,
  "twoFactor": true
}

Schema

hostedAttachbooleanrequired
methodsarray of stringrequired
quickConnectbooleanrequired
selfRegistrationstringrequired
serverIdstringrequired
serverNamestringrequired
setupRequiredbooleanrequired
twoFactorbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/auth/capabilities"

POST/v1/auth/move/codeManage the server sign-in movesession

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

Request body application/json · required

Example

{
  "code": "string"
}

Schema

codestringrequired

Responses

200Successapplication/json

Example

{
  "expiresAt": "2026-10-18T19:30:00Z",
  "signIn": "portico",
  "username": "Fargo"
}

Schema

expiresAtstringrequired
signInstringrequiredone of "portico", "local"
usernamestringrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedrevision_mismatchsign_in_kind_porticosign_in_kind_localmove_collisionmove_confirmationmove_code_invalidinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/move/code" \
  -H "Content-Type: application/json" \
  -d '{"code":"string"}'

POST/v1/auth/move/localManage the server sign-in movesession

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

Request body application/json · required

Example

{
  "code": "string",
  "password": "string",
  "username": "Fargo"
}

Schema

codestringrequired
passwordstringrequired
usernamestringrequired

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_permittedrevision_mismatchsign_in_kind_porticosign_in_kind_localmove_collisionmove_confirmationmove_code_invalidinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/move/local" \
  -H "Content-Type: application/json" \
  -d '{"code":"string","password":"string","username":"Fargo"}'

POST/v1/auth/move/passwordManage the server sign-in movesession

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

Request body application/json · required

Example

{
  "password": "string",
  "username": "Fargo"
}

Schema

passwordstringrequired
usernamestringrequired

Responses

200Successapplication/json

Example

{
  "expiresAt": "2026-10-18T19:30:00Z",
  "ticket": "string"
}

Schema

expiresAtstringrequired
ticketstringrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedrevision_mismatchsign_in_kind_porticosign_in_kind_localmove_collisionmove_confirmationmove_code_invalidinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/move/password" \
  -H "Content-Type: application/json" \
  -d '{"password":"string","username":"Fargo"}'

POST/v1/auth/move/porticoManage the server sign-in movesession

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

Request body application/json · required

Example

{
  "code": "string",
  "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"
  },
  "ticket": "string"
}

Schema

codestring
porticoIdentityobjectrequired
- certificateobject
  - keyIdstringrequired
  - notAfterstring (date-time)required
  - notBeforestring (date-time)required
  - publicKeystringrequired
  - purposestringrequired
  - revisionintegerrequired
  - revokedarray of stringrequired
  - signaturestringrequired
- keyIdstringrequired
- payloadstringrequired
- signaturestringrequired
ticketstring

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_permittedrevision_mismatchsign_in_kind_porticosign_in_kind_localmove_collisionmove_confirmationmove_code_invalidinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/move/portico" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string",
  "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"
  },
  "ticket": "string"
}'

POST/v1/auth/owner-reset/requestReset account accesssession

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

Request body application/json · required

Example

{
  "username": "Fargo"
}

Schema

usernamestring

Responses

200Successapplication/json

Example

{
  "dataDirectory": "string",
  "fileDirectory": "string",
  "fileName": "reset-code.txt",
  "retryAfterSeconds": 0,
  "systemKind": "linux"
}

Schema

dataDirectorystringrequired
fileDirectorystringrequired
fileName"reset-code.txt"required
retryAfterSecondsintegerrequired0–60
systemKindstringrequiredone of "linux", "windows", "macos", "docker"

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternalrate_limitedowner_reset_file_unavailabledatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/owner-reset/request" \
  -H "Content-Type: application/json" \
  -d '{"username":"Fargo"}'

POST/v1/auth/owner-reset/verifyReset account accesssession

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

Request body application/json · required

Example

{
  "code": "string",
  "turnOffTwoStep": true
}

Schema

codestringrequired
turnOffTwoStepboolean

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
  },
  "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": false,
  "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": "account",
      "serverId": "id_8h2k4q"
    }
  },
  "twoStepSetupRequired": true,
  "variant": "password-change"
}

Schema

accountobjectrequired
- allowedLibrariesarray of stringrequired
- disabledbooleanrequired
- disabledAtstring
- disabledReasonstring
- hostedAccountIdstring
- idstringrequired
- primaryProfileIdstringrequired
- revisionintegerrequired
- rolestringrequired
- usernamestringrequired
authoritystringrequired
canManagebooleanrequired
capabilitiesobjectrequired
- manageAccountbooleanrequired
- managePeoplebooleanrequired
- manageServerbooleanrequired
- manageSignInbooleanrequired
custodyPendingboolean
deviceIdstring
installationIdstring
managePinRequiredboolean
passwordChangeRequiredtruerequired
profilesarray of objectrequired
- allowedLibrariesarray of stringrequired
- artstringrequired
- idstringrequired
- namestringrequired
- pinRequiredbooleanrequired
- pinRevisionintegerrequired
- positionintegerrequired
- primarybooleanrequired
- revisionintegerrequired
rememberProfilesbooleanrequired
resetFileOwnerSessionfalse
serverIdstringrequired
sessionobjectrequired
- accessTokenstringrequired
- authorizationHorizonstringrequired
- deviceIdstringrequired
- expiresAtstringrequired
- installationIdstringrequired
- refreshTokenstringlength 0–0
- serverIdentityobject
  - fingerprintstringrequired
  - publicKeystringrequired
- sessionFamilyIdstringrequired
- tokenGenerationstringrequired
- viewerobjectrequired
  - accountIdstringrequired
  - authoritystringrequired
  - profileIdstringrequired
  - rolestringrequiredone of "account"
  - serverIdstringrequired
twoStepSetupRequiredboolean
variant"password-change"required

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternalrate_limitedowner_reset_expireddatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/owner-reset/verify" \
  -H "Content-Type: application/json" \
  -d '{"code":"string","turnOffTwoStep":true}'

POST/v1/auth/portico-return/exchangeComplete a registered Portico Account returnsession

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

Parameters

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

Request body application/json · required

Example

{
  "code": "string",
  "expectedRevision": "r12",
  "installationId": "id_8h2k4q",
  "moveCode": "string",
  "moveTicket": "string",
  "purpose": "string",
  "registrationId": "id_8h2k4q",
  "requestId": "id_8h2k4q",
  "serverChallenge": "string",
  "setupToken": "string",
  "transactionId": "id_8h2k4q",
  "verifier": "string"
}

Schema

codestringrequired
expectedRevisionstring
installationIdstringrequired
moveCodestring
moveTicketstring
purposestringrequired
registrationIdstringrequired
requestIdstring
serverChallengestringrequired
setupTokenstring
transactionIdstringrequired
verifierstringrequired

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_limitedsign_in_kind_porticosign_in_kind_localaccess_refusedaccount_move_waitingmove_collisionmove_code_invalidportico_services_unavailableinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/portico-return/exchange" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string",
  "expectedRevision": "r12",
  "installationId": "id_8h2k4q",
  "moveCode": "string",
  "moveTicket": "string",
  "purpose": "string",
  "registrationId": "id_8h2k4q",
  "requestId": "id_8h2k4q",
  "serverChallenge": "string",
  "setupToken": "string",
  "transactionId": "id_8h2k4q",
  "verifier": "string"
}'

POST/v1/auth/portico-return/preparePrepare a return from an existing verified server originsession

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

Parameters

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

Request body application/json · required

Example

{
  "nonce": "string",
  "origin": "string"
}

Schema

noncestringrequired
originstringrequired

Responses

200Successapplication/json

Example

{
  "challenge": "string",
  "claimOperationId": "id_8h2k4q",
  "context": {
    "payload": "string",
    "signature": "string"
  },
  "expiresAt": "2026-10-18T19:30:00Z",
  "hostedOrigin": "string",
  "proof": {
    "payload": "string",
    "signature": "string"
  },
  "registration": {
    "id": "id_8h2k4q",
    "origin": "string"
  },
  "serverId": "id_8h2k4q"
}

Schema

challengestringrequired
claimOperationIdstringrequired
contextobjectrequired
- payloadstringrequired
- signaturestringrequired
expiresAtstringrequired
hostedOriginstringrequired
proofobjectrequired
- payloadstringrequired
- signaturestringrequired
registrationobjectrequired
- idstringrequired
- originstringrequired
serverIdstringrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedrate_limitedsign_in_kind_localportico_services_unavailableinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/portico-return/prepare" \
  -H "Content-Type: application/json" \
  -d '{"nonce":"string","origin":"string"}'

POST/v1/auth/refreshRun sign-in refreshsession

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

Request body application/json · required

Example

{
  "installationId": "id_8h2k4q",
  "refreshToken": "string",
  "requestId": "id_8h2k4q"
}

Schema

installationIdstringrequired
refreshTokenstringrequired
requestIdstringrequired

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",
  "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
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/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"installationId":"id_8h2k4q","refreshToken":"string","requestId":"id_8h2k4q"}'

POST/v1/auth/registerRun sign-in registersession

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

Request body application/json · required

Example

{
  "invitationCode": "string",
  "password": "string",
  "username": "Fargo"
}

Schema

invitationCodestring
passwordstringrequired
usernamestringrequired

Responses

201Successapplication/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_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"invitationCode":"string","password":"string","username":"Fargo"}'

POST/v1/auth/remembered-accountsList the accounts remembered on this installationsession

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

Request body application/json · required

Example

{
  "installationId": "id_8h2k4q"
}

Schema

installationIdstringrequired

Responses

200Successapplication/json

Example

{
  "items": [
    {
      "accountId": "id_8h2k4q",
      "automaticSignIn": true,
      "avatarUrl": "https://example.com/…",
      "avatarVersion": 0,
      "displayName": "Fargo",
      "lastUsed": "string",
      "username": "Fargo"
    }
  ]
}

Schema

itemsarray of objectrequired
- accountIdstringrequired
- automaticSignInbooleanrequired
- avatarUrlstring
- avatarVersionintegerrequired
- displayNamestringrequired
- lastUsedstringrequired
- usernamestringrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/remembered-accounts" \
  -H "Content-Type: application/json" \
  -d '{"installationId":"id_8h2k4q"}'

GET/v1/auth/services-reachabilityCheck whether Portico Services answersopen

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

Responses

200Successapplication/json

Example

{
  "checkedAt": "2026-10-18T19:30:00Z",
  "configured": true,
  "reachable": true
}

Schema

checkedAtstring
configuredbooleanrequired
reachablebooleanrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/auth/services-reachability"

POST/v1/auth/two-factor/challengeRun sign-in two-factor verification challengesession

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

Request body application/json · required

Example

{
  "code": "string",
  "token": "string"
}

Schema

codestringrequired
tokenstringrequired

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_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/auth/two-factor/challenge" \
  -H "Content-Type: application/json" \
  -d '{"code":"string","token":"string"}'