Authentication and authorization

Quickstart

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:

No.	Parameter	Description
1.	Client ID	Your application's unique identifier (received from the Semansys support desk).
2.	Client secret	A secret known only to your application and the authorization server (received from the Semansys support desk).
3.	Username	The resource owner's username (the e-mail address used retrieving the API credentials).
4.	Password	The resource owner's password (received from the Semansys support desk).

Diagram

Implementation steps

1. Prepare the token request

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

Parameter	Value	Description
grant_type	password	Specifies the OAuth flow type.
client_id	your_client_id	Your application's unique identifier.
client_secret	your_client_secret	Your application's secret.
username	user_username	The resource owner's username.
password	user_password	The resource owner's password.

2. Send the Request

Using cURL

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

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

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:

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

Key response fields:

Field	Description
access_token	The bearer token to use for authentication.
token_type	The type of token (always "bearer" in this case).
expires_in	Token validity period in seconds.
refresh_token	Token used to obtain a new access token when the current one expires.
scope	Permissions granted to the access token.

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:

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

Troubleshooting

Common error responses:

Error code	Error text	Description
400	Bad Request	Invalid request parameters.
401	Unauthorized	Invalid client credentials.
403	Forbidden	User authentication failed.

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.