> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SuperOffice WebApi

> Authentication options for the SuperOffice WebAPI.

NetServer web services proide both SOAP and RESTful endpoints. SuperOffice.WebApi represents the RESTful side and comes in two **flavors**:

* RESTful endpoints
* HTTP RPC Agent endpoints

Each request needs credentials to verify your identity.

## Authorization header options

You must provide one of the following types of credential.

* BASIC authentication: Base64 Encode SuperOffice username:password
* SOTICKET authentication. Pass the SuperOffice ticket (7T:abc123==) without any encoding.
* BEARER authentication. Pass along an access token (7A:abc123==) from SuperID.
* NEGOTIATE / NTLM authentication. Initiates an Active Directory user authentication.

| Auth type | Example        | Onsite | Online |
| --------- | -------------- | :----: | :----: |
| No header |                |    x   |    x   |
| Basic     | YWrtMdo=       |    x   |        |
| SOTicket  | 7T:xyz123abc== |    x   |    x   |
| Bearer    | 8A:xyz123abc== |        |    x   |
| Negotiate |                |    x   |        |

No `Authorize` header on a request means that you either:

* have [IIS configured to handle identity][1] so that you can log in with your Active Directory, or
* that you send an **X-XSRF-TOKEN** header to prove that you have access to a logged-in session

<Note>
  You must explicitly [enable the authentication methods][4] that you want to use in the *web.config* file.
</Note>

### Basic

This Authorization header is a key entry of "Basic ", and a value equal to a base64 encoded representation of the user name, plus a colon, and password. Note the space following the word *Basic*. In the JavaScript code, we use the built-in DOM `window.btoa(...)` method to convert the value to base64.

<Note>
  Basic is not allowed in **Online**, since all usernames and passwords must flow through SuperID to get a bearer access token.
</Note>

### Bearer

### SOTicket

Alternatively, if the HTML page is running in the context of a SuperOffice web panel, and the application passes in the user's `SoCredential.Ticket`, the REST request header also supports SOTicket, instead of Basic. In that case, the Authentication header value is "SOTicket " plus the ticket string. Once again, notice the space following *SOTicket*.

When used in online, the SO-AppToken must accompany the SoTicket and set to the application secret (client\_secret) in the SO-AppToken header.

```http theme={null}
Authorization: SoTicket 7A:adasd098098sdfs0df8KJHSKh230...123dsa==
SO-AppToken: qw123f4c56770bc278017796cd16bd11
```

<Note>
  In this case, don't use the `window.btos(...)` method to convert a Ticket to base64 because the **ticket value is already base64 encoded**.
</Note>

### X-XSRF-TOKEN

With [requests][1] without an **Authorization** header, the API will try to log in using the current user's SuperOffice session. To avoid 3rd-party pages calling the API and piggy-backing off the current session, the API requires that a special HTTP header is added to these requests.

The SuperOffice pages contain an INPUT field `XSRF_TOKEN`. This field contains a random value identifying the current session. You must add an X-XSRF-TOKEN header with the random value from the input field.

The XSRF-TOKEN is also stored in a cookie for convenience. HTTP libraries like AXIOS will automatically pick up the XSRF-TOKEN cookie from the browser and add the X-XSRF-TOKEN header to your HTTP requests.

```http theme={null}
GET /api/v1/Contact/2
Accept: application/json
```

will return HTTP error 401 Unauthorized.

```http theme={null}
GET /api/v1/Contact/2
Accept: application/json
X-XSRF-TOKEN: abc1234
```

will work, and use the current user's session to read the data.

<Note>
  The user must be logged in. After the user logs out, the XSRF-TOKEN is not valid, and there is no existing session for you to re-use.
</Note>

[1]: ../../../onsite/install/netserver/setup-rest#integrated-with-active-directory

[4]: ../../config/webapi


## Related topics

- [SuperOffice.WebApi](/en/api/reference/webapi/SuperOffice.WebApi.md)
- [SuperOffice.WebApi.Authorization](/en/api/reference/webapi/SuperOffice.WebApi.Authorization.md)
- [SuperOffice WebApi Client Library](/en/api/reference/webapi/index.md)
- [WebAPI changes in SuperOffice 12.0](/release-notes/12/api/changes-webapi-12.0.342.0.md)
- [WebAPI changes in SuperOffice 12.1](/release-notes/12/api/changes-webapi-12.1.1412.md)
- [SuperOffice.WebApi.Data.User](/en/api/reference/webapi/SuperOffice.WebApi.Data.User.md)