> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/atreemo-api/get-started/authentication.md).

# Authentication

Existing Atreemo OAuth 2.0 password grant and APIM token pass-through

{% hint style="warning" %}
**Beta, runtime validation pending.** This page documents existing Atreemo authentication and the Phase 1 gateway design. Native authentication, permission and brand behaviour remains operation-specific and requires runtime validation.
{% endhint %}

Evidence labels are **published** (public Atreemo guide and Postman collection 1.34.0.0), **source-verified** (read-only inspection at source commit `ea9cb106e13aa4b9b92c01d090118742b44dd470`) and **runtime-unverified**. Source is not proof of the deployed build or effective configuration.

## Existing resource-owner password grant

Atreemo uses an OAuth 2.0 resource-owner password grant for the published native integration flow. Obtain a token directly from the approved Atreemo instance with `POST /token`; do not request it from APIM.

| Item         | Value                                         |
| ------------ | --------------------------------------------- |
| Method       | `POST`                                        |
| Token URL    | `https://<atreemo-instance>/token`            |
| Content type | `application/x-www-form-urlencoded`           |
| Form body    | `grant_type=password`, `username`, `password` |

Tokens are issued directly by the caller's relevant Atreemo instance, not APIM. The instance URL and credentials are supplied through the approved Atreemo support and onboarding process.

```shell
curl -X POST "https://<atreemo-instance>/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=<synthetic-username>" \
  --data-urlencode "password=<synthetic-password>"
```

The published response fields are `access_token`, `token_type`, `expires_in` and `userName`. Additional middleware properties are not ruled out.

```json
{
  "access_token": "<synthetic-access-token>",
  "token_type": "bearer",
  "expires_in": 1234,
  "userName": "synthetic-user"
}
```

The value `1234` is deliberately illustrative, not an observed or promised lifetime. Always use the returned `expires_in`.

The public guide shows `application/x-www-form-urlencoded/` with a trailing slash; use `application/x-www-form-urlencoded`. Startup registers `/Token`, while the published spelling is `/token`; preserve the published URL until target-instance behaviour is validated (`App_Start/Startup.Auth.cs:236–260`).

## Directly verified provider branches

Both branches of `Providers/ApplicationOAuthProvider.cs` override `GrantResourceOwnerCredentials`:

| Build condition             | Client validation                                                                                                 | Credential and ticket path                                                                                                                                                                   |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_IDENTITY` defined     | Calls `context.Validated()` without a client-secret check (`61–65`).                                              | Uses `ApplicationUserManager.FindAsync`; incorrect credentials and locked users have distinct `invalid_grant` branches, then identities and an authentication ticket are created (`68–116`). |
| `AUTH_IDENTITY` not defined | Validates only when `context.ClientId == null`; a supplied client ID is not validated by this branch (`125–133`). | Uses configured `Membership.ValidateUser`; false returns incorrect-credentials `invalid_grant`, while success resolves the membership user, adds claims and validates a ticket (`167–218`).  |

Checked-in project conditions define `TRACE;DEBUG` for Debug and `TRACE;AUTH_IDENTITY` for Release (`Atreemo.csproj:37–64`). This does not establish which configuration or overrides produced a given instance deployment. Do not add `client_id` or `client_secret` as universal requirements and do not reinterpret the native flow as client credentials.

## Lifetime, refresh and lockout

Startup provides an initial 72-hour expiry (`Startup.Auth.cs:239,253`). In both grant branches, a positive integer `AccesTokenLifeTime` can overwrite the option; its unit is hours unless `AccesTokenLifeTimeWithMinute` lowercases to `true`, in which case it is minutes (`ApplicationOAuthProvider.cs:90–114,187–211`). Effective values were not retrieved. This option mutation is not proof of one universal ticket lifetime; clients must use `expires_in`.

No refresh-token provider is configured in the inspected options and there is no refresh-grant override (`Startup.Auth.cs:248–260`, `ApplicationOAuthProvider.cs:27–265`). Do not advertise refresh tokens.

The identity-enabled branch checks a matched user's lockout state but does not call `AccessFailedAsync` on the missing-user/password path. The non-identity branch delegates to the selected membership provider; the inspected provider can update failure counts, but stored procedures, effective provider and thresholds were not inspected. Avoid automated credential-failure retry loops and do not promise one lockout response.

## Send the bearer token

Send the native token on each resource request:

```http
Authorization: Bearer <synthetic-access-token>
```

The selected Phase 1 flow is:

1. The caller obtains a native token directly from `https://<atreemo-instance>/token`, using the instance URL and credentials supplied through the approved Atreemo support and onboarding process.
2. The caller sends that token to the Staging resource base `https://api-staging.hos.accessacloud.com/atreemo-api` for validation, or to the Production resource base `https://api.hos.accessacloud.com/atreemo-api` after separately approved release steps.
3. APIM forwards the `Authorization` header unchanged to Atreemo.
4. Atreemo validates the token and applies its operation and brand checks.

Gateway routing and endpoint availability require staged release validation. Phase 1 has **no mandatory APIM subscription key**, no Hydra, no PKCE, no refresh-token flow, no client-credentials flow, no token exchange and no gateway token-acquisition endpoint. The native query parameter `Subscription_Key` on some ApiOpenAI operations is not an APIM subscription-key policy.

APIM does not issue tokens. Use the instance token URL supplied through the approved Atreemo support and onboarding process.

## Security best practices

* Use HTTPS, with TLS 1.2 or later recommended; deployed edge policy is unverified.
* Keep passwords and bearer tokens server-side in protected storage and out of URLs, logs, browser code and source control.
* Use short-lived in-memory handling where practical and honour the returned expiry rather than hard-coding one.
* Obtain least-privileged method and brand access through the approved Atreemo support and onboarding process.
* Use only approved synthetic records in non-production and redact evidence before support sharing.
* Stop after repeated credential failures; do not probe lockout thresholds.

The password grant describes this legacy API, not a recommended design for new APIs.

## Version caveat and errors

The contract derives from public API 1.34.0.0 / Release1.34, while read-only investigation says the current non-production Atreemo environment runs Release1.35. Authentication build/provider choice, lifetime, lockout, response status/body and 1.35 compatibility require runtime validation.

The explicitly inspected provider branches can return `invalid_grant` with `The user name or password is incorrect.`; the identity branch can return `The user is locked.` Not every exception is guaranteed to use either body. See [Errors](file:///8924120/introduction/errors.md) and [Permissions](file:///8924120/permissions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hos.accessacloud.com/atreemo-api/get-started/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.