# Authenticating agents against SAS Viya REST APIs

Not an agent? See the human-oriented guide at [/docs/rest-apis/getting-started/authentication](/docs/rest-apis/getting-started/authentication).

This document tells an agent, or an agent developer, everything needed to authenticate against SAS Viya REST APIs using OAuth 2.0. Follow it in order.

## What this is not

developer.sas.com is a documentation portal. It is not a SAS Viya deployment, not an OAuth authorization server, not an OpenID Connect issuer, and not a protected-resource server for SAS Viya APIs. The Okta sign-in on this site only lets a human view restricted documentation pages here; it has no bearing on SAS Viya API authentication and issues no credential usable against any Viya API.

## Overview

Every SAS Viya REST API runs inside a customer's own SAS Viya deployment, on a hostname developer.sas.com does not control and cannot know in advance. Authentication happens against that deployment's SAS Logon Manager, which implements OAuth 2.0. There is no single, fixed token endpoint: you must supply your own Viya host.

Throughout this document, `{viya-host}` is a placeholder for that hostname. Replace it with the real hostname of the deployment you are targeting before sending any request; never substitute a value that looks like a real, working host.

## Prerequisites

Before you can authenticate:

- A running SAS Viya deployment and its hostname (`{viya-host}`).
- Administrator access to that deployment, to register an OAuth client, or an already-registered client id and secret.
- The grant type your integration needs (see Supported grant types below).

## Client registration

An administrator on the target Viya deployment must register an OAuth client before any token can be issued. The [register-oauth-client skill](/.well-known/agent-skills/register-oauth-client/SKILL.md) is the source of truth for that procedure and its required parameters; follow it to obtain an administrator token, register the client with SAS Logon, and store the resulting client secret securely.

Client registration itself is a call against `{viya-host}`. This document intentionally does not duplicate the registration sequence, so changes to the registration procedure belong in the skill rather than requiring a second copy here.

## Supported grant types

| Grant type | When to use |
| --- | --- |
| `client_credentials` | Machine-to-machine integrations acting as the application itself, with no end user. Use scope `uaa.none` unless the client also needs a specific authority. |
| `authorization_code` | Flows performed on behalf of a signed-in end user, where the client must never handle the user's credentials. Requires an additional authorization-endpoint step not covered by the worked example below; see the human-oriented guide. |

`password` is not covered here: it is deprecated, unsupported under OAuth 2.1, and not recommended.

## Token endpoint

```
https://{viya-host}/SASLogon/oauth/token
```

Replace `{viya-host}` with the hostname of the reader's own Viya deployment. This endpoint does not exist on developer.sas.com.

## Scopes

- `openid`: required for `authorization_code` and any grant that acts on behalf of a user. Sufficient for most SAS Viya APIs.
- `uaa.none`: use for `client_credentials` clients that do not act on behalf of a user.
- `SASAdministrators`: include only when the client needs SAS Administrators group privileges; requires explicit opt-in even for administrators.

## Worked example

This worked example covers `client_credentials` end to end. `authorization_code` additionally requires a browser redirect to `https://{viya-host}/SASLogon/oauth/authorize` and a registered redirect URI, which are not repeated here; see the human-oriented guide linked in Where to go next for that flow.

### 1. Request a token (client_credentials)

```bash
curl -s -X POST "https://{viya-host}/SASLogon/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client-id}:{client-secret}" \
  -d "grant_type=client_credentials&scope=uaa.none"
```

If your deployment uses a self-signed certificate, add `-k` for local testing only; never disable certificate verification against a real deployment.

Response (200):

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "uaa.none"
}
```

The token expires after `expires_in` seconds (3599 above, about one hour). For `client_credentials`, request a new token when the current one expires or is rejected. For `authorization_code`, use the returned refresh token to obtain a new access token instead of repeating the authorization step.

### 2. Call a SAS Viya API with the token

```bash
curl -s "https://{viya-host}/compute/contexts" \
  -H "Authorization: Bearer {access-token}"
```

Substitute the resource path for the API you are calling; each API's own documentation on developer.sas.com gives its base path.

## Common errors

| Error | Meaning |
| --- | --- |
| `invalid_client` | The client id or secret is wrong, or the client is not registered on this `{viya-host}`. |
| `invalid_scope` | The requested scope is not one the client was registered with. |
| `unauthorized_client` | The client is not registered for the grant type requested. |
| `403` on an API call | The token is valid but lacks the scope or authority the API requires; register or request a broader scope. |

## Where to go next

- [Authentication guide (human-oriented)](/docs/rest-apis/getting-started/authentication): full walkthrough of grant types, client registration parameters, and additional language examples.
- [llms.txt](/llms.txt): curated orientation for agents, including links to every published SAS Viya API.
- [register-oauth-client skill](/.well-known/agent-skills/register-oauth-client/SKILL.md): step-by-step OAuth client registration call sequence.