@spec create(
  ArchAstro.SDK.Client.t(),
  String.t(),
  ArchAstro.SDK.Types.Operations.PostApiV1UsersUserTokens.Input.t()
) ::
  {:ok, ArchAstro.SDK.Types.SystemAccessToken.t()}
  | {:error, ArchAstro.SDK.Error.reason()}

Create a personal access token

Issues a new long-lived access token for the authenticated user. The raw JWT is returned in the token field of the response exactly once and cannot be retrieved again — store it securely immediately after creation.

scopes is optional. When omitted the token receives full_access. Known catalog scopes (for example profile) restrict the token through the same ScopeGuard used by OAuth.

expires_in_days is optional and must be one of 7, 30, 60, 90, or 365. When omitted the token lasts 30 days. Each user may hold at most 50 active tokens; exceeding that limit returns 429.

The caller must be the user identified by user and must present a first-party session (or a full_access access token). A restricted access token cannot mint another token.

The newly created access token. The token field contains the raw JWT and is present only in this response — it is not stored and cannot be retrieved later.

@spec delete(ArchAstro.SDK.Client.t(), String.t(), String.t()) ::
  {:ok, ArchAstro.SDK.Types.SystemAccessToken.t()}
  | {:error, ArchAstro.SDK.Error.reason()}

Revoke a personal access token

Permanently revokes the specified access token belonging to the authenticated user. Once revoked, the token is immediately rejected by all API endpoints and cannot be reinstated. The token record is retained and returned in the response with revoked_at populated.

The caller must be the user identified by user and must present a first-party session (or a full_access access token). Returns 404 if the token does not exist or does not belong to the caller.

The revoked access token. The revoked_at field is populated with the time of revocation.

@spec list(ArchAstro.SDK.Client.t(), String.t()) ::
  {:ok, ArchAstro.SDK.Types.Operations.GetApiV1UsersUserTokens.Response.t()}
  | {:error, ArchAstro.SDK.Error.reason()}

List personal access tokens

Returns all access tokens associated with the authenticated user, including active and revoked tokens. Tokens are returned without their raw JWT values — the plaintext JWT is only available at creation time.

The caller must be the user identified by user and must present a first-party session (or a full_access access token).

Successful response