Authentication

Authentication

To access the protected functions of the API, authentication must be performed on the server.

Important Terminology

• JWT Token: A time-limited token that must be used to access the server. The token is by default only valid for 15 minutes.
• Authentication Token: Valid for two months by default. It can be used to fetch a new JWT token anytime needed.
• roSessionID: Required to access the legacy SwissMentor DA server. It is valid for one hour.

Authentication Flow

Authentication using REST

To authenticate a user and get a JWT and authentication token, use the following REST call:

POST https://{{SERVERNAME}}/auth/login

HTTP Header: Content-Type: application/json

Request Body:

{
  "username": "user",
  "password": "pass"
}

Response:

{
  "jwtToken": "eyJhbGciOiJI....",
  "authenticationToken": "ey....",
  "header": "Bearer eyJhbGciOiJIUz..."
}

Response Codes:

• 200 OK - Successful authentication
• 400 Bad Request - Input validation error
• 401 Unauthorized - Password expired, OTP required, or invalid credentials

Sample using curl

curl --request POST \
     --url https://your.server/auth/login \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"username":"admin", "password": "password"}'

Using the token:

export TOKEN="jwttoken..."
curl -X POST \
     -H "Content-Type: application/graphql" \
     -H "Authorization: Bearer $TOKEN" \
     --data 'query { me { username} }' \
     https://your.server/graphql

Login in Apollo GraphQL Sandbox

To execute queries in the Apollo GraphQL Sandbox, a JWT token must be supplied.

Using the Pre-request Script

const response = await explorer.fetch('http://localhost:4099/auth/login', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    username: explorer.environment.get('username'),
    password: explorer.environment.get('password'),
  }),
});
const data = response.json();
explorer.environment.set('jwtToken', data.jwtToken);

Manual Login Process

1. Login using the sandbox by using the login query to get a JWT token:

2. The generated JWT token must be used as HTTP header for all following GraphQL requests. Enter the new token in the Headers section on the bottom left:

3. Run the following query to check if the token is valid:

query {
  me {
    session {
      username
      isAdmin
    }
  }
}

If everything is correct, you should get a result like:

{
  "data": {
    "me": {
      "session": {
        "username": "USERNAME",
        "isAdmin": true
      }
    }
  }
}

Token Expiration

Remember, the JWT token expires after 15-60 minutes. If the JWT token expires, you need to login again and get a new JWT token.

PowerShell Example

Complete login and data fetching example:

$url = "http://localhost:4099/graphql"

# Login and fetch JWT token
$headers = @{
  "content-type" = "application/json"
}
$body = @'
{ "query": "mutation { login(username:\"USERNAME\", password:\"PASSWORD\") { jwtToken } }" }
'@
$result = Invoke-WebRequest -Uri $url -Method POST -Body $body -Headers $headers
$data = $result.Content | ConvertFrom-Json
$jwtToken = $data.data.login.jwtToken
Write-Output "Login ok - jwt token $jwtToken"

# Execute a command using JWT Token
$headers = @{
    "content-type" = "application/json"
    "Authorization" = "Bearer $jwtToken"
}
$body = @'
{ "query": "query { object(id:\"1\") { name } }"  }
'@
$result = Invoke-WebRequest -Uri $url -Method POST -Body $body -Headers $headers
$data = $result.Content | ConvertFrom-Json
Write-Output $data.data.object.name

Authentication using GraphQL (Legacy)

Legacy Method

This method is still supported but the REST authentication method is preferred.

A login can be made with the following mutation:

mutation {
  login(username: "USERNAME", password: "PASSWORD") {
    jwtToken
    authenticationToken
  }
}

Response:

{
  "data": {
    "login": {
      "jwtToken": "eyJhbGciOiJIUzI1NiIsI [.....]",
      "authenticationToken": "eyJhbGciOiJIUzI1 [...]"
    }
  }
}

Token Refresh

When your JWT token expires, you can use the authentication token to get a new JWT token without re-entering credentials:

curl --request POST \
     --url https://your.server/auth/refresh \
     --header 'content-type: application/json' \
     --data '{"authenticationToken": "your-auth-token"}'

Logout (Disable Authentication Token)

If the authentication token is not used anymore, it should be disabled on the server:

mutation ($authenticationToken: String!) {
  disableAuthenticationToken(authenticationToken: $authenticationToken)
}

Security Best Practices

Token Storage

• Never store JWT tokens in localStorage in web applications
• Use secure HTTP-only cookies when possible
• Store authentication tokens securely (encrypted storage)

Token Handling

• Always use HTTPS in production
• Implement proper token refresh logic
• Handle token expiration gracefully
• Log out users when tokens are compromised

Development vs Production

• Use shorter token lifetimes in production
• Enable additional security features (2FA, IP restrictions)
• Monitor authentication attempts
• Implement rate limiting

Troubleshooting

Common Issues

Error	Cause	Solution
401 Unauthorized	Invalid credentials	Check username/password
401 Token Expired	JWT token expired	Refresh token or re-authenticate
403 Forbidden	Insufficient permissions	Check user roles and permissions
400 Bad Request	Invalid request format	Verify JSON structure

Testing Authentication

# Test if you're authenticated
query {
  me {
    session {
      username
      roles
      permissions
    }
  }
}

Next Steps

• Persons API - Work with person data

Weitere API-Dokumentation (Gruppen, Objekte, etc.) folgt in Kürze.