> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/xytech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/xytech/rest-api/connecting-and-authenticating.md).

# Connecting and Authenticating

### Licensing

The REST API is a licensed component.

### Information You Will Need

To be able to connect with the REST API, you will need to know the instance details:

| Detail        | e.g.                  | Comment                                                 |
| ------------- | --------------------- | ------------------------------------------------------- |
| Site Base URL | <https://example.com> | This is the same base URL you use to access your system |
| Database Name | DEMO1                 | Instance database name                                  |

### API URL

The API URL is constructed as follows:

`{Site Base URLl}/api/v2/database/{dbname}/{endpoint}`&#x20;

e.g. `https://example.com/mysite/api/v2/database/demo1/JmJob`

For systems installed prior to mid 2023, you may also require the port number. All later systems are now setup with a proxy to avoid the need to know the port number.

If you do not have this information, please contact Xytech Technical Support.

### API Users & Permissions

An API user needs to have been created as a user in the Platform. The user, must be enabled for REST API access by flagging 'Allow API Login' on the user setup. \
As with all users, assign appropriate security roles (enable as a super user is not recommended).

### Authenticating

#### OAuth 2.0 OpenID Authentication for REST API

Two methods are supported

* Client Credentials method (system to system access)
* SPA / browser sign-in method (interactive user authentication flow)

Pre-requisites Your auth provider has been configured and the Xytech app server has been configured. (Azure and Okta/Auth0)

Client-Credentials method, from auth provider you needs:

* Access token URL
* Client ID
* Client Secret
* Scope

For SPA method you need:

* Authorisation URL
* Access token URL
* Client ID
* Client Secret
* Scope

Summary flow:\
\- Obtain token from auth provider \
\- Use token to make REST API calls until token expires.

#### JWT Token authentication

For use case scenarios where database user accounts are employed, using the JWT Token may be the prefered method. \
Typical use might be for system to system authentication requirements.

Pre-requisite\
Xytech app server has been configured for JWT authentication

Summary flow:\
\- Retrieve token passing login credentials in the POST body \
\- Use token for all subsequent API calls, until token expires

Below are the URLs for login and token refresh.

`{{baseURL}}/api/v2/database/{{dbName}}/orchestration/auth/login`\
`{{baseURL}}/api/v2/database/{{dbName}}/orchestration/auth/refresh`

cURL Example:

```json
curl --location 'https://devwcumpapp2.xytech.xytechsystems.com/xyt_main/orchestration/api/v2/database/XYT_MAIN_V/auth/login' \
--header 'Content-Type: application/json' \
--data '{
    
    "username":"username",
    "password":"password"
    
}'
```

Refresh example:

```json
curl --location 'https://devwcumpapp2.xytech.xytechsystems.com/xyt_main/orchestration/api/v2/database/XYT_MAIN_V/auth/refresh' \
--header 'Content-Type: application/json' \
--data '{
    "accessToken": "xxx",
    "refreshToken": "xxx"
}'
```

See additional authentication user guides for more details.

#### Basic Authentication

The REST API uses Basic Authentication and will require a login account.\
Always use HTTPS encrypted protocol when communicating with the REST API to ensure credentials are not passed in clear text.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://knowledgebase.fabricdata.com/xytech/rest-api/connecting-and-authenticating.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.