Authentication
This page covers how to authenticate your requests to the Journyx API, and how to choose the right method for your integration.
Authentication methods
The Journyx API offers three ways to authenticate API calls:
- Session-cookie authentication — sign in once
at the
/api/v1/loginendpoint and reuse awtsessioncookie. Recommended for server-side scripts and automation. - OAuth 2.1 Bearer tokens — a user-delegated flow for client apps. Recommended for apps a person signs into, such as mobile, desktop, and third-party integrations.
- HTTP Basic Authentication — credentials sent on every request. Discouraged, and disabled by default on new sites.
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.
Choosing a method
| Your integration | Use this |
|---|---|
| An app a person signs into (mobile, desktop, third-party, AI/agent client) | OAuth 2.1 Bearer tokens |
| Your own server-side scripts, scheduled jobs, or system-to-system sync | API Key + session cookie |
| Quick testing or exploration | Session cookie |
Two rules of thumb:
- Prefer session cookies or Bearer tokens over HTTP Basic Auth. Basic Auth re-authenticates on every request, which is slower, and it is turned off by default on new sites.
- Use OAuth only for user-delegated apps. OAuth always involves a person signing in and consenting; there is no machine-to-machine (client-credentials) grant. For unattended automation, use an API Key with the session-cookie flow.
Credentials vs. authentication methods
It helps to separate two ideas:
- A credential proves who you are. Journyx accepts your account password or an API Key (a password substitute).
- An authentication method carries that proof to the server: a session cookie, an OAuth Bearer token, or HTTP Basic Auth.
Passwords and API Keys are used with the session-cookie and HTTP Basic methods. OAuth is different: after the user consents once, your app holds a Bearer token and no longer sends a password or API Key at all.
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
Note: your account must have the appropriate abilities to create API Keys.
An API Key is a password substitute for the session-cookie and HTTP Basic methods. It is the right choice for unattended, server-side integrations. It is not used with OAuth, which relies on a user consenting in a browser instead.
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:
-
Log In: Access your Journyx account through the web application.
-
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".
-
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.
-
Create New API Key: Click on "Create a new API Key".
-
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.
-
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/loginendpoint, 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.
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.
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.
Session-cookie authentication
Session-cookie authentication is the recommended method for server-side scripts
and automation. It involves obtaining a wtsession cookie, which serves as a
temporary authentication token.
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. It also works out of the box, whereas HTTP Basic Auth is disabled by default on new sites.
Obtaining a wtsession Cookie
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.
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.
Using the wtsession Cookie
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.
OAuth 2.1 Bearer tokens
For applications that a user signs into — mobile and desktop apps, third-party integrations, and AI/agent clients — Journyx supports OAuth 2.1 with user-delegated Bearer tokens. Instead of a shared password or API Key, the user signs in and consents to a specific set of scopes, and your app receives an access token it presents on each request:
GET /api/v1/endpoint HTTP/1.1
Host: example.apps.journyx.com
Authorization: Bearer OPAQUE_ACCESS_TOKEN
OAuth uses the Authorization Code flow with PKCE, and requires a licensed, admin-enabled authorization server. The full flow — discovery, authorization, token exchange, refresh, scopes, and error handling — is documented on the dedicated OAuth 2.1 page.
OAuth is a licensed feature and must be enabled by an administrator. For unattended automation without a user present, use an API Key with session-cookie authentication instead — there is no machine-to-machine OAuth grant.
HTTP Basic Authentication
HTTP Basic Authentication sends your credentials with every request. It is useful for quick tests and simple scripts, but it is less performant than the session-cookie or Bearer-token methods, and we discourage it for production use.
As of Journyx 14.1, HTTP Basic Authentication for the API is turned off by default on new sites. If you need it, an administrator must enable it under System Settings > Security. Existing sites that upgrade keep their current setting. We recommend using session-cookie authentication or OAuth Bearer tokens instead.
Using HTTP Basic Authentication
Include an Authorization header with your username and password or API Key
encoded in Base64.
Steps:
- Combine Credentials:
username:password_or_api_key - Encode in Base64: Use Base64 encoding on the combined string.
- Set Authorization Header: Include the encoded string in the
Authorizationheader.
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 session-cookie authentication for server-side integrations: this combination offers enhanced security and performance.
- Use OAuth Bearer tokens for apps that a user signs into, so access is consented and can be revoked per app.
- Secure Your Credentials: Never expose your passwords, API Keys, or tokens in client-side code or insecure storage.
- Monitor Expiration Dates: Keep track of your API Key,
wtsession, and access-token expiration dates to prevent authentication failures. - Set Appropriate Permissions: Use read-only API Keys for applications that don't require data modification, and request only the OAuth scopes your app needs.
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 session-cookie authentication:
-
Generate an API Key: Follow the steps in Generating an API Key.
-
Authenticate and Obtain
wtsessionCookie:Request:
POST /api/v1/login HTTP/1.1Origin: example.apps.journyx.comAccept: application/jsonX-Requested-With: XMLHttpRequestContent-Type: application/json{"username": "apiuser","password": "your_api_key"}Response:
HTTP/1.1 200 OKSet-Cookie: wtsession=abc123sessiontoken; Path=/; Secure; HttpOnlyX-Session-Id: abc123sessiontokenContent-Type: application/json{"success": true} -
Make Authenticated Requests: Include the
wtsessioncookie in theCookieheader.Request:
GET /api/v1/projects HTTP/1.1Host: example.apps.journyx.comCookie: wtsession=abc123sessiontoken