Skip to main content

Authentication

This page covers how to authenticate your requests to the Journyx API.

Authentication basics​

The Journyx API currently offers two primary methods of authentication for API calls:

Both methods can utilize either regular account passwords or API Keys, which can be used in place of a password for API authentication.

Other authentication methods

There are other authentication techniques common in other APIs, such as OAuth2, or JSON Web Tokens (JWT). These are not currently supported by the Journyx API, but support for these methods may be added in the future.

Authentication vs authorization

It's important to note the distinction between authentication and authorization:

  • Authentication is the process of verifying the identity of a user or system.

  • Authorization is the process of determining what actions a user or system can perform.

In the Journyx system, authorization to perform actions is primarily controlled by your roles (which grant abilities), along with your Groups configuration and other system settings. This page covers authentication, or the process of verifying your identity. The authorization (abilities or permissions) to perform any given action are usually covered in the specific endpoint documentation.

API Keys​

API Keys offer a secure way to authenticate to the Journyx API without using your regular account password. They are particularly useful because they are compatible with Single Sign-On (SSO) configurations and provide additional security features. They can be created in the Journyx web application under the "API Keys" section of the "My Settings" menu. They can also be created programmatically at the API endpoint /api/v1/api_keys/generate_api_key

API Key Permissions

Note: your account must have the appropriate abilities to create API Keys.

Benefits of Using API Keys​

  • SSO Compatibility: Allows users to interact with the API when the site uses Single Sign-On (SSO).
  • Mandatory Expiration: API Keys have a mandatory expiration date, enhancing security by limiting the window of access.
  • Optional Read-Only Mode: Can be configured to restrict actions to read-only, preventing any data modifications.
  • Avoid using password directly: Prevents the need to expose your account password in client-side code or scripts.

Generating an API Key​

To create an API Key:

  1. Log In: Access your Journyx account through the web application.

  2. Navigate to My Settings: In the upper right area of the application, click on the Profile menu (the one with your name), then click "My Settings".

  3. Access API Keys Section: Scroll down to the "Security and Identity" section. You should see an API Keys section here, including a button labeled "Create a new API Key". If you do not see this, you may not have the necessary abilities to create API Keys. Check the API Key abilities section below, and ask your administrator to adjust your account if necessary.

  4. Create New API Key: Click on "Create a new API Key".

  5. Configure Key Settings:

    • Key name: give an optional name to help identify this key if you have more than one.
    • Set Permissions: Select read-only access as needed.
    • Set Days Before Expiration: Choose the number of days the key is valid for.

  6. Click OK to create the key: After clicking OK, you will be shown the actual API Key. You can copy the key shown onto the clipboard by clicking the Copy button.

    This key can then be used in place of a password when signing in to the /api/v1/login endpoint, or when using Basic Authentication.

Note that when creating a key on behalf of another user, you will not be shown the actual key. The other user can retrieve the new API Key by going to their My Settings screen and clicking on the Details button for the key.

Create API Keys in the API

If you need to create or maintain a large amount of API Keys, you may find it helpful to use /api/v1/api_keys/generate_api_key and related endpoints to manage API Keys programmatically.

API Key abilities​

Note: You must have the necessary abilities to create API Keys. Namely, the following abilities are required:

  • API Key - Generate - needed to create API Keys for yourself.

  • API Key - Sign In - this is needed to actually use an API Key, whether you generated it yourself or an administrator did on your behalf. If you do not have this ability, the sign-in attempt or API access will be denied.

  • API Key - Manage - needed to create API Keys for other users.

If you are missing these abilities, you may need to assign them to yourself (if you are an Administrator), or else contact your Journyx Administrator to have them assigned.

Abilities are granted through Roles

Note that abilities are always assigned through a role which contains one or more abilities. Abilities cannot be assigned directly to users. Therefore, you will need to have a role assigned which contains API Key abilities. This can be a custom role or one of the built-in API Key roles.

Cookie-based authentication is the recommended method for authenticating Journyx API requests. It involves obtaining a wtsession cookie, which serves as a temporary authentication token.

Why use cookie auth?

Although HTTP Basic Auth can be simpler to use, especially for quick or one-off scripts or testing, we recommend using cookie-based authentication for most cases. It is more secure and more performant, especially for long-running applications or scripts.

To get a wtsession cookie, use the Sign-In Endpoint by sending your username and password or API Key.

Request Example:

A more complete example of using the /api/v1/login endpoint with a detailed explanation can be found in the tutorial section on authentication.

Using request headers

The following example illustrates how certain request headers are required on all POST requests for security reasons, including /api/v1/login. These are the Origin, Accept, and X-Requested-With headers, and they are discussed more in this tutorial section.

POST /api/v1/login HTTP/1.1
Origin: example.apps.journyx.com
Accept: application/json
X-Requested-With: XMLHttpRequest
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password_or_api_key"
}

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json
X-Session-Expires: 1729903436.26, 2024-10-25T19:43:56.264769, 102000.00
X-Session-Id: XniUfTHe33meiYrwfhLB8aldBshQHsKFPzvq4Vb9wGfHVms3mcP9k2orYzYv0nPn_TmJqR6iHsUFLfTTWYirMg
Set-Cookie: wtsession=XniUfTHe33meiYrwfhLB8aldBshQHsKFPzvq4Vb9wGfHVms3mcP9k2orYzYv0nPn_TmJqR6iHsUFLfTTWYirMg; Path=/; HttpOnly; SameSite=Strict

{
  "success": true,
  "auth": {
    "abilities": [...],
    "expires": 172811387,
    ...
  }
}

The server responds with a Set-Cookie header containing the wtsession token. It's important to note that the wtsession token is not included in the actual response body, only in the headers; both the Set-Cookie header and the X-Session-Id header contain the same value. The X-Session-Id header is provided in case you need to extract the token programmatically and can't access the Set-Cookie header due to client restrictions.

The X-Session-Expires header also gives additional information about when the session will expire, including the Unix epoch time of expiration, along with a human-readable date and time, and the number of seconds until expiration.

Include the wtsession token in the Cookie header of all subsequent API requests.

Request Example with Cookie:

GET /api/v1/endpoint HTTP/1.1
Host: example.apps.journyx.com
Cookie: wtsession=your_session_token

Important: The wtsession token expires after a certain period. You'll need to re-authenticate to obtain a new token when it expires. The expiration period depends on the settings in System Settings > Security.

HTTP Basic Authentication​

HTTP Basic Authentication is useful for testing and simple scripts but is less performant compared to cookie-based authentication, as it requires credentials with each request.

Using HTTP Basic Authentication​

Include an Authorization header with your username and password or API Key encoded in Base64.

Steps:

  1. Combine Credentials: username:password_or_api_key
  2. Encode in Base64: Use Base64 encoding on the combined string.
  3. Set Authorization Header: Include the encoded string in the Authorization header.

Example:

If your username is apiuser and your password or API Key is secretkey, combine them:

apiuser:secretkey

Encode the string in Base64:

YXBpdXNlcjpzZWNyZXRrZXk=

Include it in your request:

GET /api/v1/endpoint HTTP/1.1
Host: example.apps.journyx.com
Authorization: Basic YXBpdXNlcjpzZWNyZXRrZXk=

How to encode the string in Base64 will vary depending on your programming language or tool. Most programming languages have built-in functions for encoding strings in Base64.

Python example of Base64 encoding​

In Python, you can use the built-in base64 module to encode your credentials.

import base64

username = 'apiuser'
password = 'secretkey'

# Combine username and password with a colon
credentials = f'{username}:{password}'

# Convert the credentials to bytes
credentials_bytes = credentials.encode('utf-8')

# Encode the bytes in Base64
base64_bytes = base64.b64encode(credentials_bytes)

# Convert the Base64 bytes back to a string
base64_credentials = base64_bytes.decode('utf-8')

# Prepare the Authorization header
headers = {
    'Authorization': f'Basic {base64_credentials}'
}

# Example of making a request using the requests library
import requests

url = 'https://example.apps.journyx.com/api/v1/endpoint'

response = requests.get(url, headers=headers)

print(response.status_code)
print(response.text)

Best Practices​

  • Use API Keys with Cookie-Based Authentication: This combination offers enhanced security and performance.
  • Secure Your Credentials: Never expose your passwords or API Keys in client-side code or insecure storage.
  • Monitor Expiration Dates: Keep track of your API Key and wtsession token expiration dates to prevent authentication failures.
  • Set Appropriate Permissions: Use read-only API Keys for applications that don't require data modification.
Security reminder

Always use HTTPS (encrypted mode) when making API requests to ensure your credentials are encrypted (protected) during transmission. Only HTTPS is enabled on Journyx application servers.

Avoid hardcoding credentials in your code, especially if the code will be shared or stored in version control systems. Consider using environment variables or secure credential storage mechanisms.

Example Workflow​

Here's a step-by-step example of authenticating using an API Key with cookie-based authentication:

  1. Generate an API Key: Follow the steps in Generating an API Key.

  2. Authenticate and Obtain wtsession Cookie:

    Request:

    POST /api/v1/login HTTP/1.1
    Origin: example.apps.journyx.com
    Accept: application/json
    X-Requested-With: XMLHttpRequest
    Content-Type: application/json

    {
      "username": "apiuser",
      "password": "your_api_key"
    }

    Response:

    HTTP/1.1 200 OK
    Set-Cookie: wtsession=abc123sessiontoken; Path=/; Secure; HttpOnly
    X-Session-Id: abc123sessiontoken
    Content-Type: application/json

    {
      "success": true
    }

  3. Make Authenticated Requests: Include the wtsession cookie in the Cookie header.

    Request:

    GET /api/v1/projects HTTP/1.1
    Host: example.apps.journyx.com
    Cookie: wtsession=abc123sessiontoken