API reference

Authentication

19 operationsBase URL https://packetexchange.io/api/v1Postman collection

BrowseAuthentication

Create an account

POST/api/v1/auth/register

Access: Public. No key needed.
Rate limit: 200 requests per hour

Creates the account, emails a verification link and signs you in. acceptTerms must be true. An invite code, when given, adds test credit once the email is verified. Returns the same session payload as login.

Request body (application/json)

Field	Type	Description
`email`required	string (email)	-
`password`required	string	-max 128 chars
`contactName`required	string	-max 255 chars
`companyName`	string	-max 255 chars
`country`	string	-max 2 chars
`inviteCode`	string	-
`acceptTerms`required	boolean	-One of `true`

Response 201

Field	Type	Description
`data`required	object	-
`accessToken`requireddata.accessToken	string	JWT access token. Send as `Authorization: Bearer <token>`.
`refreshToken`requireddata.refreshToken	string	Refresh token (7 days). Also set as an httpOnly cookie scoped to /api/v1/auth.
`expiresIn`requireddata.expiresIn	integer	Access-token lifetime in seconds (900)
`user`requireddata.user	object	-
`id`requireddata.user.id	string (uuid)	-
`email`requireddata.user.email	string (email)	-
`contactName`requireddata.user.contactName	string	-
`companyName`requireddata.user.companyName	string \| null	-
`jobTitle`requireddata.user.jobTitle	string \| null	-
`phone`requireddata.user.phone	string \| null	-
`country`requireddata.user.country	string \| null	ISO-3166-1 alpha-2
`timezone`requireddata.user.timezone	string	-
`companyLogoUrl`requireddata.user.companyLogoUrl	string \| null	-
`avatarUrl`requireddata.user.avatarUrl	string \| null	-
`role`requireddata.user.role	string	-One of `user`, `admin`
`status`requireddata.user.status	string	-One of `active`, `suspended`
`accountKind`requireddata.user.accountKind	string	-
`balance`requireddata.user.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`testCredit`requireddata.user.testCredit	money	Sandbox credit, spendable only by test API keys USD as a decimal string with exactly 6 places, e.g. "0.012500".
`emailVerifiedAt`requireddata.user.emailVerifiedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`pendingEmail`requireddata.user.pendingEmail	string \| null	An address change waiting for confirmation
`verificationStatus`requireddata.user.verificationStatus	string	-One of `unverified`, `verified`
`kycStatus`requireddata.user.kycStatus	string	-One of `not_started`, `pending`, `verified`, `rejected`
`totpEnabled`requireddata.user.totpEnabled	boolean	Two-factor authentication is on
`taxId`requireddata.user.taxId	string \| null	-
`taxCountry`requireddata.user.taxCountry	string \| null	-
`payoutMethod`requireddata.user.payoutMethod	string \| null	-
`onboardingGoal`requireddata.user.onboardingGoal	string \| null	-
`onboardingDismissed`requireddata.user.onboardingDismissed	boolean	-
`onboardingSeen`requireddata.user.onboardingSeen	boolean	-
`emailNotificationsOptOut`requireddata.user.emailNotificationsOptOut	boolean	-
`switchStatus`requireddata.user.switchStatus	string	-One of `none`, `active`, `past_due`, `canceled`, `comp`
`createdAt`requireddata.user.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.user.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "password": "correct-horse-battery-staple",
  "contactName": "<contactName>",
  "acceptTerms": true
}'

Run it here, no key needed.

Log in with email and password

POST/api/v1/auth/login

Access: Public. No key needed.
Rate limit: 20 requests per 5 minutes

Returns an access token, a refresh token and your profile. When two-factor authentication is on, returns { mfaRequired: true, mfaToken } instead: complete the login with POST /auth/2fa/verify. Repeated failures lock the account temporarily.

Request body (application/json)

Field	Type	Description
`email`required	string (email)	-
`password`required	string	-max 128 chars

Response 200

Field	Type	Description
`data`required	object	-
`accessToken`data.accessToken	string	JWT access token. Send as `Authorization: Bearer <token>`.
`refreshToken`data.refreshToken	string	Refresh token (7 days). Also set as an httpOnly cookie scoped to /api/v1/auth.
`expiresIn`data.expiresIn	integer	Access-token lifetime in seconds (900)
`user`data.user	object	Same fields as AccountProfile, shown earlier on this page.
`mfaRequired`data.mfaRequired	boolean	-One of `true`
`mfaToken`data.mfaToken	string	Short-lived (5 minutes) token to send with a TOTP code to POST /auth/2fa/verify

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "password": "correct-horse-battery-staple"
}'

Run it here, no key needed.

Complete a two-factor login

POST/api/v1/auth/2fa/verify

Access: Public. No key needed.
Rate limit: 15 requests per 5 minutes

Exchanges the mfaToken from login plus an authenticator (or backup) code for a session.

Request body (application/json)

Field	Type	Description
`mfaToken`required	string	From the login response
`code`required	string	6-digit authenticator code, or one of your backup codes

Response 200

Field	Type	Description
`data`required	object	Same fields as AuthSession, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/2fa/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "mfaToken": "<mfaToken>",
  "code": "482913"
}'

Run it here, no key needed.

Refresh an access token

POST/api/v1/auth/refresh

Access: Public. No key needed.
Rate limit: 100 requests per second (the default)

Reads the refresh token from the httpOnly cookie, or from the body for non-browser clients. Rotates the refresh token: store the new one. Cross-site browser requests are refused with CSRF_BLOCKED; a missing token is MISSING_TOKEN.

Request body (application/json)

Field	Type	Description
`refreshToken`	string	-

Response 200

Field	Type	Description
`data`required	object	-
`accessToken`requireddata.accessToken	string	JWT access token. Send as `Authorization: Bearer <token>`.
`refreshToken`requireddata.refreshToken	string	Refresh token (7 days). Also set as an httpOnly cookie scoped to /api/v1/auth.
`expiresIn`requireddata.expiresIn	integer	Access-token lifetime in seconds (900)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoMISSING_TOKEN, CSRF_BLOCKED

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "<refreshToken>"
}'

Run it here, no key needed.

Log out the current session

POST/api/v1/auth/logout

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Revokes only this session (other devices stay signed in) and clears the refresh cookie.

Response 200

Field	Type	Description
`data`required	object	-
`message`requireddata.message	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your active sessions

GET/api/v1/auth/sessions

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Signed-in devices, most recently seen first. current marks the one making the request.

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`ip`requireddata[].ip	string \| null	-
`userAgent`requireddata[].userAgent	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`lastSeenAt`requireddata[].lastSeenAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`current`requireddata[].current	boolean	True for the session making this request (matched via the refresh token)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Sign out one session

DELETE/api/v1/auth/sessions/{id}

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Sign out every other session

POST/api/v1/auth/sessions/revoke-others

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Keeps the current session. Needs the refresh token (cookie or body) to know which session is current; without it the answer is NO_SESSION.

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoNO_SESSION

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/sessions/revoke-others" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN"

Session-only: run it from the dashboard.

Verify your email address

POST/api/v1/auth/verify-email

Access: Public. No key needed.
Rate limit: 100 requests per second (the default)

Consumes the token from the verification email. Any invite-code test credit is added at this point.

Request body (application/json)

Field	Type	Description
`token`required	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Confirm an email address change

POST/api/v1/auth/confirm-email-change

Access: Public. No key needed.
Rate limit: 10 requests per 10 minutes

Finishes a change requested with POST /account/email, using the token from the link sent to the NEW address. Public on purpose: the single-use token is the proof, so the link works on any device.

Request body (application/json)

Field	Type	Description
`token`required	string	The token from the confirmation link sent to the new address

Response 200

Field	Type	Description
`data`required	object	-
`email`requireddata.email	string (email)	The address now on the account

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/confirm-email-change" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "<token>"
}'

Run it here, no key needed.

Resend the verification email

POST/api/v1/auth/resend-verification

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Redeem an invite code after sign-up

POST/api/v1/auth/invite/redeem

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 10 requests per 10 minutes

For social sign-ups, or a code mistyped at registration. ok: false carries the reason. When the email is not verified yet, the credit is held (pending: true) and added on verification.

Request body (application/json)

Field	Type	Description
`code`required	string	-max 64 chars

Response 200

Field	Type	Description
`data`required	object	-
`ok`requireddata.ok	boolean	-
`amount`data.amount	money	Test credit granted USD as a decimal string with exactly 6 places, e.g. "0.012500".
`pending`data.pending	boolean	True when the credit waits for email verification
`reason`data.reason	string	Why the code was not applied

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/invite/redeem" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "482913"
}'

Run it here with a test key.

Resend a verification email by address

POST/api/v1/auth/resend-verification-public

Access: Public. No key needed.
Rate limit: 5 requests per hour

For users whose link expired and who cannot sign in. Always answers the same way, whether or not the account exists.

Request body (application/json)

Field	Type	Description
`email`required	string (email)	-

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/resend-verification-public" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com"
}'

Run it here, no key needed.

Request a password reset email

POST/api/v1/auth/forgot-password

Access: Public. No key needed.
Rate limit: 5 requests per hour

Always answers the same way, whether or not the account exists.

Request body (application/json)

Field	Type	Description
`email`required	string (email)	-

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com"
}'

Run it here, no key needed.

Reset your password with a reset token

POST/api/v1/auth/reset-password

Access: Public. No key needed.
Rate limit: 15 requests per hour

Request body (application/json)

Field	Type	Description
`token`required	string	-
`newPassword`required	string	-max 128 chars

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "<token>",
  "newPassword": "<newPassword>"
}'

Run it here, no key needed.

Change your password

POST/api/v1/auth/change-password

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Requires the current password. Signs out every session, including this one once its access token expires, and emails a confirmation.

Request body (application/json)

Field	Type	Description
`currentPassword`required	string	-
`newPassword`required	string	At least 8 characters and different from the current password

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/auth/change-password" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "currentPassword": "<currentPassword>",
  "newPassword": "<newPassword>"
}'

Session-only: run it from the dashboard.

List the social login providers that are enabled

GET/api/v1/auth/oauth/providers

Access: Public. No key needed.
Rate limit: 100 requests per second (the default)

Response 200

Field	Type	Description
`data`required	object	-
`google`requireddata.google	boolean	-
`linkedin`requireddata.linkedin	boolean	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Start a social login

GET/api/v1/auth/oauth/{provider}/start

Access: Public. No key needed.
Rate limit: 100 requests per second (the default)

A browser navigation, not an API call. Redirects to the provider; next is a same-site path to land on afterwards.

Parameters

Name	In	Type	Description
`provider`required	path	string	-One of google, linkedin
`next`	query	string	Relative path to open after signing in, e.g. /dashboard

Response 302

Redirect to the provider, or to /login?oauth_error=unavailable when the provider is not configured.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Finish a social login (provider callback)

GET/api/v1/auth/oauth/{provider}/callback

Access: Public. No key needed.
Rate limit: 100 requests per second (the default)

Called by the provider after consent. Signs the browser in and redirects into the app, or to /login?oauth_error=... on failure.

Parameters

Name	In	Type	Description
`provider`required	path	string	-One of google, linkedin
`code`	query	string	-
`state`	query	string	-
`error`	query	string	-

Response 302

Redirect into the app when signed in, or to /login with an oauth_error reason.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.