# Authentication and authorization

## How to retrieve a bearer token using OAuth password grant flow

### Overview

The OAuth 2.0 password grant flow allows applications to obtain an access token by directly collecting the user's credentials. This guide explains how to implement this flow to retrieve a bearer token using client credentials and user authentication.

### Prerequisites

Before you begin, ensure you have the following credentials:

<table><thead><tr><th width="75.6666259765625">No.</th><th width="147.333251953125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>1.</td><td><strong>Client ID</strong></td><td>Your application's unique identifier (received from the Semansys support desk).</td></tr><tr><td>2.</td><td><strong>Client secret</strong></td><td>A secret known only to your application and the authorization server (received from the Semansys support desk).</td></tr><tr><td>3.</td><td><strong>Username</strong></td><td>The resource owner's username (the e-mail address used retrieving the API credentials).</td></tr><tr><td>4.</td><td><strong>Password</strong></td><td>The resource owner's password (received from the Semansys support desk).</td></tr></tbody></table>

### Diagram

<figure><img src="/files/ZML3FpuMaz0v5u1Ja64K" alt=""><figcaption></figcaption></figure>

### Implementation steps

#### 1. Prepare the token request

Create a POST request to the token endpoint with the following parameters:

<table><thead><tr><th width="179">Parameter</th><th width="198">Value</th><th>Description</th></tr></thead><tbody><tr><td>grant_type</td><td><code>password</code></td><td>Specifies the OAuth flow type.</td></tr><tr><td>client_id</td><td><em>your_client_id</em></td><td>Your application's unique identifier.</td></tr><tr><td>client_secret</td><td><em>your_client_secret</em></td><td>Your application's secret.</td></tr><tr><td>username</td><td><em>user_username</em></td><td>The resource owner's username.</td></tr><tr><td>password</td><td><em>user_password</em></td><td>The resource owner's password.</td></tr></tbody></table>

#### 2. Send the Request

**Using cURL**

```bash
curl -X POST https://oidc-pre.semansys.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "username=USER_USERNAME" \
  -d "password=USER_PASSWORD"
```

**Using JavaScript/Node.js**

```javascript
const axios = require('axios');
const qs = require('querystring');

const data = {
  grant_type: 'password',
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
  username: 'USER_USERNAME',
  password: 'USER_PASSWORD'
};

axios.post('https://oidc-pre.semansys.com/connect/token', 
  qs.stringify(data), 
  {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  })
  .then(response => {
    console.log('Access Token:', response.data.access_token);
  })
  .catch(error => {
    console.error('Error:', error.response ? error.response.data : error.message);
  });
```

**Using Python**

```python
import requests

url = "https://oidc-pre.semansys.com/connect/token"
payload = {
    "grant_type": "password",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "username": "USER_USERNAME",
    "password": "USER_PASSWORD"
}

response = requests.post(url, data=payload)
response_data = response.json()

print("Access Token:", response_data.get("access_token"))
```

#### 3. Parse the Response

Upon successful authentication, the server will respond with a JSON object containing:

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "scope": "read write"
}
```

Key response fields:

<table><thead><tr><th width="188.6666259765625">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>access_token</strong></td><td>The bearer token to use for authentication.</td></tr><tr><td><strong>token_type</strong></td><td>The type of token (always "bearer" in this case).</td></tr><tr><td><strong>expires_in</strong></td><td>Token validity period in seconds.</td></tr><tr><td><strong>refresh_token</strong></td><td>Token used to obtain a new access token when the current one expires.</td></tr><tr><td><strong>scope</strong></td><td>Permissions granted to the access token.</td></tr></tbody></table>

#### 4. Use the bearer token

To use the bearer token for API requests, include it in the Authorization header:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Example request with the bearer token:

```bash
curl -X GET https://api.semansys.com/... \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Troubleshooting

Common error responses:

<table><thead><tr><th width="167.66668701171875">Error code</th><th width="173.66668701171875">Error text</th><th>Description</th></tr></thead><tbody><tr><td><strong>400</strong></td><td><strong>Bad Request</strong></td><td>Invalid request parameters.</td></tr><tr><td><strong>401</strong></td><td><strong>Unauthorized</strong></td><td>Invalid client credentials.</td></tr><tr><td><strong>403</strong></td><td><strong>Forbidden</strong></td><td>User authentication failed.</td></tr></tbody></table>

If you receive an error, check:

* All required parameters are included and correctly formatted
* Client id and client secret are valid
* User credentials are correct.


---

# Agent Instructions: 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:

```
GET https://docs.semansys.com/getting-started/quickstart/authentication-and-authorization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.