Check whether the current bearer token is valid

GET

/v1/authenticated

const url = 'https://api.aetherpush.com/v1/authenticated';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.aetherpush.com/v1/authenticated \
  --header 'Authorization: Bearer <token>'

Lightweight session-validation endpoint. Returns 200 with { authenticated: true } if the bearer token is valid and not expired; 401 otherwise. Useful for the dashboard to verify on boot whether the cached session is still alive.

Two address limiters can answer 429 here. The process-wide limiter admits 100 requests per minute from an address across every route. This operation then applies its own limiter of 100 requests per 15 minutes. Neither is the tenant management limiter.

Authorizations

accessKeyAuth
apiKeyAuth

Responses

200

Token is valid.

application/json

object

authenticated

required

boolean

Example

{
  "authenticated": true
}

401

Token is missing, invalid, or expired.

application/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The session or access key being used is invalid, please run \"aether login\" again.",
  "code": "session_or_key_invalid",
  "requestId": "req_abc123"
}

403

The request did not arrive through the trusted edge. This operation is not behind the tenant or account-freeze guards, so those 403s are not reachable here.

application/json

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "Forbidden",
  "code": "forbidden",
  "requestId": "req_abc123"
}

429

Two causes share this status. The process-wide address limiter answers GlobalAddressRateLimitErrorResponse with Retry-After and draft RateLimit-* (see info.description § Process-wide address limiter). This operation’s own address limiter (100 requests per 15 minutes on auth.router()) answers the stock express-rate-limit string as text/html, with Retry-After and legacy X-RateLimit-*. A rapid burst hits the process-wide limiter first; after that window resets, further calls within the 15-minute budget hit the route limiter. Neither body is the tenant RateLimitErrorResponse.

GlobalAddressRateLimitError

Returned with HTTP 429 when the process-wide address limiter (100 requests per minute across every published path) is spent. Distinct from RateLimitErrorResponse: this body has no retryAfterSeconds field. Prefer matching on code. See info.description § Process-wide address limiter.

object

error

required

string

code

required

string

Allowed value: too_many_requests

Example

{
  "error": "Too many requests",
  "code": "too_many_requests"
}

Headers

Retry-After

integer

>= 1

Seconds until the limiter that answered resets.