REST API

Credentials

Store account material for capabilities that require it.

Some capabilities require an authenticated account on the upstream platform. Upscrape stores that credential material separately from your Upscrape API key and associates it with your account.

## Endpoints

```text
GET    /credentials
POST   /credentials
GET    /credentials/:id
PATCH  /credentials/:id
DELETE /credentials/:id
POST   /credentials/:id/validate
```

All requests use the normal Upscrape bearer token. List requests may be filtered by `platform`.

## Response safety

Credential responses contain metadata such as ID, platform, label, authentication mode, status, validation timestamps, and errors. They do not return the decrypted credential payload.

## Validation semantics

The current `POST /credentials/:id/validate` operation decrypts the stored blob to verify its integrity and marks the record active when decryption succeeds.

It does **not** currently prove that the upstream platform will accept the credential. A capability execution can still fail because a session expired, permissions changed, or the upstream platform rejected it.

## Use credentials

If a capability requires upstream authentication and no suitable credential exists, execution returns HTTP `422` with `credentials_required`. Store the required credential, verify its metadata, then create a new logical execution.

## Rotation

Update or replace expiring platform credentials before they are used by scheduled jobs. Delete credentials that are no longer needed. Never place upstream tokens or cookies in module manifests, examples, knowledgebase notes, or public documentation.

Some capabilities require an authenticated account on the upstream platform. Upscrape stores that credential material separately from your Upscrape API key and associates it with your account.

Endpoints

GET    /credentials
POST   /credentials
GET    /credentials/:id
PATCH  /credentials/:id
DELETE /credentials/:id
POST   /credentials/:id/validate

All requests use the normal Upscrape bearer token. List requests may be filtered by platform.

Response safety

Credential responses contain metadata such as ID, platform, label, authentication mode, status, validation timestamps, and errors. They do not return the decrypted credential payload.

Validation semantics

The current POST /credentials/:id/validate operation decrypts the stored blob to verify its integrity and marks the record active when decryption succeeds.

It does not currently prove that the upstream platform will accept the credential. A capability execution can still fail because a session expired, permissions changed, or the upstream platform rejected it.

Use credentials

If a capability requires upstream authentication and no suitable credential exists, execution returns HTTP 422 with credentials_required. Store the required credential, verify its metadata, then create a new logical execution.

Rotation

Update or replace expiring platform credentials before they are used by scheduled jobs. Delete credentials that are no longer needed. Never place upstream tokens or cookies in module manifests, examples, knowledgebase notes, or public documentation.