Authentication

The TypeScript SDK uses a pre-issued bearer token. Obtain an API token (PAT) from accounts.spacecomputer.io and use the API origin, https://op.spacecomputer.io.

Install the SDK

Install the SDK in your project:

npm install @spacecomputer-io/orbitport-sdk-ts

With Bun, use:

bun add @spacecomputer-io/orbitport-sdk-ts

Configure your token

Keep the token on your server and outside source control:

export ORBITPORT_ACCESS_TOKEN="your-api-token"
export ORBITPORT_API_URL="https://op.spacecomputer.io"

Pass these values explicitly to the SDK:

import { OrbitportSDK } from "@spacecomputer-io/orbitport-sdk-ts";

const accessToken = process.env.ORBITPORT_ACCESS_TOKEN;
if (!accessToken) throw new Error("Set ORBITPORT_ACCESS_TOKEN");

const sdk = new OrbitportSDK({
  config: {
    accessToken,
    apiUrl: process.env.ORBITPORT_API_URL ?? "https://op.spacecomputer.io",
  },
});

The SDK sends Authorization: Bearer <token> on KMS requests. It does not acquire, refresh, or persist a configured token. Client ID, client secret, auth-domain, and audience options are not part of the SDK configuration.

The SDK defaults apiUrl to https://op.spacecomputer.io when omitted. Environment variables and .env files are loaded by your application runtime, not by the SDK.

Inspect and replace a token

const isValid = await sdk.auth.isTokenValid();
const tokenInfo = await sdk.auth.getTokenInfo();
// { valid: boolean, expiresAt?: number }; expiresAt is Unix time in seconds.

sdk.updateConfig({ accessToken: "your-replacement-token" });

These helpers inspect local token state. For parseable JWTs, the SDK checks expiry with a 60-second buffer. Other non-empty bearer tokens are passed to the gateway for validation. A local valid: true is not a signature, permission, or revocation check: the gateway validates the token and the account service enforces account access.

A missing token causes KMS requests to fail with AUTH_FAILED. An expired JWT detected locally causes TOKEN_EXPIRED. Supply a replacement token when needed; there is no automatic refresh.

Token storage

If accessToken is omitted, the SDK can read a caller-populated TokenStorage. A configured token takes precedence over storage.

await sdk.auth.clearToken(); // clears token storage only

clearToken() emits token_cleared. It does not clear a configured accessToken, request a new token, or revoke a token on the server. To stop using a configured token locally, call sdk.updateConfig({ accessToken: undefined }) and clear token storage as well.

Authenticate without the SDK

Use the same token with an HTTP client. For example, discover the gateway's KMS capabilities:

curl --fail-with-body --request POST \
  --url "${ORBITPORT_API_URL}/api/v1/rpc" \
  --header "Authorization: Bearer ${ORBITPORT_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"kms.GetCapabilities","params":{}}'

Orbitport's backend also validates legacy Auth0-issued bearer tokens. The SDK accepts an already-issued token through accessToken; it does not perform an OAuth client-credentials exchange. Internal service credentials used to issue PATs are separate from customer API tokens and are not accepted as customer credentials.

KMS operations require authentication.

Next steps

• Use the KMS -- create keys, encrypt, decrypt, sign, and store JSON secrets.
• Orbitport Architecture -- understand authentication and tenant isolation.