Authentication

Uplink authenticates with OAuth 2.0 client credentials. You create an OAuth client in Uplink Console, then pass its client ID and secret to the JavaScript SDK, which exchanges them for an access token on your behalf.

Create an OAuth client

Open your project's settings

In Uplink Console, go to Projects and select the settings icon on the project you want to create credentials for.

Open the OAuth clients dialog

In the OAuth Clients section, select Manage OAuth clients, then Create OAuth client.

Configure the client

Give the client a name that identifies where it runs — for example CI pipeline or Checkout automation. Leave the token expiry fields at their defaults unless you have a reason to change them.

Save your credentials

Select Create OAuth client. Console shows the client ID and client secret, then asks you to confirm you’ve stored them.

.env

UPLINK_CLIENT_ID=upoc_...
UPLINK_CLIENT_SECRET=upocs_...

The client secret is shown once, when you create the client. Copy it before closing the dialog. If you lose it, use Rotate secret to issue a new one — the old secret stops working immediately.

Use the credentials

Pass your client ID and secret to uplink.session() as the first argument:

import uplink from '@uplink-code/uplink'

const session = await uplink.session(
  {
    clientId: process.env.UPLINK_CLIENT_ID,
    clientSecret: process.env.UPLINK_CLIENT_SECRET
  },
  {
    include: { ecdsa: true, ecdh: true }
  }
)

const client = await uplink.client.fromSession(session)

The same credentials object works for uplink.getSession() and uplink.sessionDetails():

const credentials = {
  clientId: process.env.UPLINK_CLIENT_ID,
  clientSecret: process.env.UPLINK_CLIENT_SECRET
}

const session = await uplink.getSession(credentials, '<existing-session-id>')
const details = await uplink.sessionDetails(
  credentials,
  '<existing-session-id>'
)

The SDK handles the token exchange for you. It requests an access token the first time you make a call, reuses it across subsequent calls, and requests a new one before the old one expires.

An OAuth client is granted a fixed set of permissions when you create it. If you’d rather a particular workload run with less than that, the credentials object also accepts a scope option that narrows what the resulting access token is allowed to do.

Reuse an access token

If you’d rather hold the access token yourself — to share it across processes, or to inspect it — mint one with uplink.token() and pass the result anywhere credentials are accepted:

const token = await uplink.token({
  clientId: process.env.UPLINK_CLIENT_ID,
  clientSecret: process.env.UPLINK_CLIENT_SECRET
})

const session = await uplink.session(token, {
  include: { ecdsa: true, ecdh: true }
})
const details = await uplink.sessionDetails(token, session.sessionId)

A token you hold yourself is not renewed for you. When it expires, calls made with it fail — call uplink.token() again with your client credentials to get a new one. Pass the credentials directly instead if you don’t want to manage this.

Keep your client secret safe

Treat the client secret like a password. Read it from an environment variable or a secrets manager, and never commit it or expose it in client-side code.

// ✓ Good: from the environment
const session = await uplink.session({
  clientId: process.env.UPLINK_CLIENT_ID,
  clientSecret: process.env.UPLINK_CLIENT_SECRET
})

// ✗ Bad: hardcoded
const session = await uplink.session({
  clientId: 'upoc_abc123...',
  clientSecret: 'upocs_def456...'
})

Create a separate client for each environment or workload so you can rotate or disable one without disrupting the others. You can rotate a secret, disable a client, or delete it entirely from the OAuth Clients dialog in Console.

Introduction

Fundamentals

MCP Server

Authentication

Create an OAuth client

Use the credentials

Reuse an access token

Keep your client secret safe

Next steps

Sessions

Client API

​Create an OAuth client

​Use the credentials

​Reuse an access token

​Keep your client secret safe

​Next steps

Sessions

Client API

Create an OAuth client

Use the credentials

Reuse an access token

Keep your client secret safe

Next steps