Get Location Status

POST

locations

status

curl -X POST https://api.byteport.com/v1/locations/status \
  -H "Authorization: Bearer $BYTEPORT_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "marketing-assets" }'

const res = await fetch("https://api.byteport.com/v1/locations/status", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
    "User-Agent": "my-app/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "marketing-assets" }), // or { id: "..." }
});
const status = await res.json();

import os, requests

status = requests.post(
    "https://api.byteport.com/v1/locations/status",
    headers={
        "Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
        "User-Agent": "my-app/1.0",
    },
    json={"name": "marketing-assets"},  # or {"id": "..."}
).json()

{
  "status":                       "active",
  "rotation_class":               "oauth-stable",
  "access_token_expires_at":      "2026-07-07T18:30:00Z",
  "refresh_requested":            false,
  "consecutive_refresh_failures": 0,
  "last_refresh_attempt_at":      "2026-07-06T02:11:04Z"
}

{
  "error": 404,
  "message": "no location named marketing-assets"
}

Return the non-secret refresh state of a location — its lifecycle status, rotation class, access-token expiry, and recent refresh history. Use it to check on a location after calling Refresh, or to monitor the health of an OAuth token over time. Address the location by name or id; at least one is required. This is a POST because the target rides in the request body. A non-unique name returns 409 with the candidates — resend with the id of the one you want.

curl -X POST https://api.byteport.com/v1/locations/status \
  -H "Authorization: Bearer $BYTEPORT_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "marketing-assets" }'

const res = await fetch("https://api.byteport.com/v1/locations/status", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
    "User-Agent": "my-app/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "marketing-assets" }), // or { id: "..." }
});
const status = await res.json();

import os, requests

status = requests.post(
    "https://api.byteport.com/v1/locations/status",
    headers={
        "Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
        "User-Agent": "my-app/1.0",
    },
    json={"name": "marketing-assets"},  # or {"id": "..."}
).json()

{
  "status":                       "active",
  "rotation_class":               "oauth-stable",
  "access_token_expires_at":      "2026-07-07T18:30:00Z",
  "refresh_requested":            false,
  "consecutive_refresh_failures": 0,
  "last_refresh_attempt_at":      "2026-07-06T02:11:04Z"
}

{
  "error": 404,
  "message": "no location named marketing-assets"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Address the location by name or id.

name

string

The location name (its label). Resolved to a single location; if the name matches several, also send id to pick one.

Example:

"prod-backups"

string

The location's UUID. Addresses one location directly, or — alongside name — selects which match of a non-unique name to act on.

Example:

"3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83"

Response

The location's refresh status.

The non-secret refresh state of a credential, returned by the Status endpoints.

status

enum<string>

Lifecycle state of the credential.

Available options:

active,

failed,

needs_attention

Example:

"active"

validation_error

string

Provider-side reason the credential was marked failed. Omitted when active.

Example:

"invalid_grant"

rotation_class

string

How the credential's secret rotates. Populated for OAuth providers (oauth-stable, oauth-single-use); omitted for static credentials that don't rotate.

Example:

"oauth-stable"

access_token_expires_at

string<date-time>

For OAuth providers, when the cached access token expires (RFC 3339). Omitted for providers without expiring access tokens.

Example:

"2026-07-07T18:30:00Z"

refresh_requested

boolean

Whether a refresh is currently queued for this credential (set by the Refresh endpoint, cleared once the refresher runs).

Example:

false

consecutive_refresh_failures

integer

Count of back-to-back failed refresh attempts. Resets to 0 on a successful refresh.

Example:

0

last_refresh_attempt_at

string<date-time>

When the refresher last attempted this credential (RFC 3339). Omitted if never attempted.

Example:

"2026-07-06T02:11:04Z"

last_refresh_error

string

Error from the most recent refresh attempt. Omitted when the last attempt succeeded or none has run.

Example:

"temporary network error"

Refresh Location

Delete Location

curl -X POST https://api.byteport.com/v1/locations/status \
  -H "Authorization: Bearer $BYTEPORT_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "marketing-assets" }'

const res = await fetch("https://api.byteport.com/v1/locations/status", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
    "User-Agent": "my-app/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "marketing-assets" }), // or { id: "..." }
});
const status = await res.json();

import os, requests

status = requests.post(
    "https://api.byteport.com/v1/locations/status",
    headers={
        "Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
        "User-Agent": "my-app/1.0",
    },
    json={"name": "marketing-assets"},  # or {"id": "..."}
).json()

{
  "status":                       "active",
  "rotation_class":               "oauth-stable",
  "access_token_expires_at":      "2026-07-07T18:30:00Z",
  "refresh_requested":            false,
  "consecutive_refresh_failures": 0,
  "last_refresh_attempt_at":      "2026-07-06T02:11:04Z"
}

{
  "error": 404,
  "message": "no location named marketing-assets"
}