Authentication

This guide covers how to obtain Orbitport API credentials, configure them in the SDK, and authenticate without the SDK if needed.

Get your credentials

1. Go to accounts.spacecomputer.io and sign up for an account.
2. Once signed in, create an application. The dashboard gives you a Client ID and a Client Secret.
3. Copy both — you will use them as your OAuth2 client credentials. The Client Secret is shown only once, so store it somewhere safe (a password manager, a secret store, an .env file outside source control).

Configure credentials in the SDK

Pass your credentials to the SDK constructor:

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

const sdk = new OrbitportSDK({
  config: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  },
});

The SDK runs the full OAuth2 client-credentials flow for you. On the first authenticated call (sdk.ctrng.random(), sdk.kms.*, etc.), the SDK will:

1. Request an access token from the auth server (https://auth.spacecomputer.io/oauth/token).
2. Cache the token and reuse it for subsequent requests.
3. Refresh the token automatically when it expires.

If you need to inspect the cached token state:

const isValid = await sdk.auth.isTokenValid();
const tokenInfo = await sdk.auth.getTokenInfo();
await sdk.auth.clearToken(); // force a fresh token on the next call

Use environment variables

Keep credentials out of source code by loading them from the environment:

export ORBITPORT_CLIENT_ID=<your-client-id>
export ORBITPORT_CLIENT_SECRET=<your-client-secret>

const sdk = new OrbitportSDK({
  config: {
    clientId: process.env.ORBITPORT_CLIENT_ID,
    clientSecret: process.env.ORBITPORT_CLIENT_SECRET,
  },
});

ORBITPORT_CLIENT_ID and ORBITPORT_CLIENT_SECRET are the names the SDK's own examples and tests use, so any other code you copy from the SDK repo will line up.

Use the SDK without credentials

If you do not pass clientId and clientSecret, the SDK skips authentication entirely and reads cTRNG values from the public IPFS beacon:

const sdk = new OrbitportSDK({ config: {} });

// No auth needed -- this reads from the IPFS beacon.
const result = await sdk.ctrng.random();

When credentials are provided but the API is unreachable, the SDK also falls back to IPFS automatically.

:::note Credential-less mode applies to cTRNG only. KMS operations always require a Client ID and Secret -- there is no IPFS-equivalent fallback for key management. :::

Authenticate without the SDK

If you need to call the Orbitport API directly (for example, from a language without an SDK or from a shell script), do the OAuth2 client-credentials exchange yourself.

Get an access token

ACCESS_TOKEN=$(curl --silent --request POST \
  --url "https://auth.spacecomputer.io/oauth/token" \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"'"${ORBITPORT_CLIENT_ID}"'",
    "client_secret":"'"${ORBITPORT_CLIENT_SECRET}"'",
    "audience":"https://op.spacecomputer.io/api",
    "grant_type":"client_credentials"
  }' \
  | jq -r '.access_token')

Call an authenticated endpoint

Pass the token as a Bearer token:

curl --request GET \
  --url https://op.spacecomputer.io/api/v1/services/trng \
  --header "authorization: Bearer ${ACCESS_TOKEN}"

Tokens are valid for a finite window (typically 24 hours). Cache them and refresh when expired -- which is exactly what the SDK does for you.

Next steps

• Fetch cTRNG values -- read cosmic randomness from the API or the public IPFS beacon.
• Use the KMS -- create keys, encrypt, decrypt, and sign with managed keys.
• Orbitport Architecture -- understand how authentication fits into the system.