Authentication

The SensorUp GraphQL API supports multiple authentication methods depending on your use case and environment.

Authentication Methods

Method	Use Case	Lifetime	MFA Support
Session-based	Interactive web applications	7-30 days idle, 30-365 days max (varies by client)	Yes
API Keys	Machine-to-machine, integrations	60 days idle, 365 days max	No
Federated Sign-in	SSO integration	Same as session-based	Via SSO provider

All authentication methods use the same session ID mechanism - either via the sensorup_sessionid cookie (browser) or x-sensorup-sessionid header (API clients).

Session-Based Authentication

Session-based authentication is the primary method for interactive applications where users log in with username and password.

mutation SignIn($input: AuthSignInInput!) {
  signIn(input: $input) {
    session {
      username
      authenticated
      expiresAt
      expiresAtHard
      userGroup
      challengeName
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "loginUsername": "user@example.com",
    "password": "your-password",
    "clientApplicationType": "EXPLORER"
  }
}

Session Response

{
  "data": {
    "signIn": {
      "session": {
        "username": "user@example.com",
        "authenticated": true,
        "expiresAt": "2025-11-05T18:00:00Z",
        "expiresAtHard": "2025-11-06T10:00:00Z",
        "userGroup": "your-tenant-id",
        "challengeName": null
      },
      "correlationId": "abc-123",
      "errors": []
    }
  }
}

Checking Current Session

query GetSession {
  session {
    username
    authenticated
    expiresAt
    userGroup
    lastAuthenticatedAt
  }
}

Sign Out

mutation SignOut {
  signOut {
    session {
      authenticated
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Using Your Session

After successful sign-in, your session ID is used to authenticate subsequent API requests. There are two methods: When you sign in through a web browser, the sensorup_sessionid cookie is automatically set and sent with each request:

Cookie: sensorup_sessionid=YOUR_SESSION_ID

This happens automatically - you don’t need to manually set this cookie in browser applications.

2. Header Authentication (Machine-to-Machine)

For API clients, mobile apps, and integrations, pass the session ID in the x-sensorup-sessionid header:

curl -X POST https://customer-demo.sensorup.com/api/graphql \
  -H "Content-Type: application/json" \
  -H "x-sensorup-sessionid: YOUR_SESSION_ID" \
  -d '{"query":"{ session { username authenticated } }"}'

Using with HTTP clients:

// JavaScript/Node.js
fetch('https://customer-demo.sensorup.com/api/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-sensorup-sessionid': sessionId
  },
  body: JSON.stringify({ query: '{ session { username } }' })
})

# Python
import requests

response = requests.post(
    'https://customer-demo.sensorup.com/api/graphql',
    headers={
        'Content-Type': 'application/json',
        'x-sensorup-sessionid': session_id
    },
    json={'query': '{ session { username } }'}
)

Multi-Factor Authentication (MFA)

When MFA is required, the sign-in mutation returns a challengeName:

MFA Challenge Response

{
  "session": {
    "username": "user@example.com",
    "authenticated": false,
    "challengeName": "SMS_MFA",
    "challengeParam": {}
  }
}

Challenge Types

Challenge	Description
`SMS_MFA`	SMS-based one-time code
`SOFTWARE_TOKEN_MFA`	TOTP authenticator app
`MFA_SETUP`	MFA setup required
`NEW_PASSWORD_REQUIRED`	Password reset required

Completing MFA Challenge

mutation ConfirmSignIn($input: AuthConfirmSignInInput!) {
  confirmSignIn(input: $input) {
    session {
      username
      authenticated
      expiresAt
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "code": "123456",
    "mfaType": "SMS_MFA"
  }
}

API Key Authentication

API keys are designed for machine-to-machine communication and integration scenarios. API keys generate sessions just like user logins, but with longer lifetimes.

Creating an API Key

mutation CreateAPIKey($input: AuthCreateAPIKeyInput!) {
  createAPIKey(input: $input) {
    apiKey {
      apiKeyId
      apiKeySessionId
      username
      authenticated
      expiresAt
      userGroup
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "apiKeyId": "my-integration-key",
    "userGroup": "your-tenant-id"
  }
}

The response includes an apiKeySessionId which is the session ID you’ll use for authentication.

API keys provide full access to the API with the same permissions as the user who created them. Store them securely and rotate them regularly.

Using API Keys

Use the API key session ID in the x-sensorup-sessionid header (same as regular sessions):

curl -X POST https://customer-demo.sensorup.com/api/graphql \
  -H "Content-Type: application/json" \
  -H "x-sensorup-sessionid: YOUR_API_KEY_SESSION_ID" \
  -d '{"query":"{ session { username } }"}'

Integration Example:

// Store the API key session ID securely
const apiKeySessionId = process.env.SENSORUP_API_KEY_SESSION_ID

// Use in requests
const response = await fetch('https://customer-demo.sensorup.com/api/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-sensorup-sessionid': apiKeySessionId
  },
  body: JSON.stringify({ query: '{ session { username } }' })
})

AWS Credentials

For accessing AWS services (S3, etc.), you can obtain temporary AWS credentials:

Getting AWS Credentials

query GetCredentials($group: String) {
  credentials(group: $group) {
    accessKeyId
    secretAccessKey
    sessionToken
    expiration
  }
}

Response:

{
  "data": {
    "credentials": {
      "accessKeyId": "ASIA...",
      "secretAccessKey": "...",
      "sessionToken": "...",
      "expiration": "2025-11-05T18:00:00Z"
    }
  }
}

Using AWS Credentials

import AWS from 'aws-sdk'

// Configure AWS SDK with credentials from GraphQL
AWS.config.credentials = new AWS.Credentials({
  accessKeyId: credentials.accessKeyId,
  secretAccessKey: credentials.secretAccessKey,
  sessionToken: credentials.sessionToken
})

// Use AWS services
const s3 = new AWS.S3()

For organizations using SSO, you can authenticate with Cognito tokens:

mutation FederatedSignIn($input: AuthFederatedSignInInput!) {
  federatedSignIn(input: $input) {
    session {
      username
      authenticated
      expiresAt
      userGroup
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "cognitoIdToken": "your-id-token",
    "clientApplicationType": "EXPLORER"
  }
}

SSO configuration is tenant-specific. Contact your SensorUp account team for SSO setup and configuration.

Session Management

Session Expiration

Sessions have two expiration times:

Soft Expiry (Idle Timeout): Session extends with activity up to this limit
Hard Expiry (Maximum Lifetime): Absolute maximum session duration - requires re-authentication after this time

Session lifetimes vary by client application type:

Client Application Type	Hard Expiry (Max Lifetime)	Soft Expiry (Idle Timeout)
Explorer (Web)	30 days	7 days
SensorHub Android	365 days	60 days
SensorHub iOS	365 days	60 days
API Key	365 days	60 days

How it works:

If you’re actively using the API, your session stays valid until the hard expiry time
If you’re inactive for longer than the soft expiry (idle timeout), the session expires
After hard expiry, you must sign in again regardless of activity
The expiresAt field in the session response reflects the current soft expiry time
The expiresAtHard field shows the absolute maximum session lifetime

Switching User Groups

If your user has access to multiple tenant groups:

mutation SetUserGroup($input: AuthSetSessionUserGroupInput!) {
  setSessionUserGroup(input: $input) {
    session {
      userGroup
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "userGroup": "different-tenant-id"
  }
}

Re-authentication

For sensitive operations, you may need to re-authenticate:

mutation Reauthenticate($input: ReauthenticationInput!) {
  reauthenticate(input: $input) {
    session {
      username
      authenticated
      lastAuthenticatedAt
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "password": "your-password"
  }
}

Device Management

Track and manage authenticated devices:

Listing Devices

query GetUserDevices($userId: ID!) {
  user(id: $userId) {
    devices {
      deviceKey
      name
      remembered
      createdAt
      lastSignedInAt
      lastIpAddress
    }
  }
}

Forgetting Devices

mutation ForgetDevices($input: AuthForgetSpecificDevicesInput!) {
  forgetDevices(input: $input) {
    session {
      username
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "deviceKeys": ["device-key-1", "device-key-2"]
  }
}

Password Management

Forgot Password

mutation ForgotPassword($input: AuthForgotPasswordInput!) {
  forgotPassword(input: $input) {
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "loginUsername": "user@example.com"
  }
}

Reset Password

mutation ForgotPasswordSubmit($input: AuthForgotPasswordSubmitInput!) {
  forgotPasswordSubmit(input: $input) {
    session {
      username
      authenticated
    }
    correlationId
    errors {
      message
      type
    }
  }
}

Variables:

{
  "input": {
    "loginUsername": "user@example.com",
    "confirmationCode": "123456",
    "password": "new-password"
  }
}

Authentication Configuration

Query authentication configuration for your environment:

query GetAuthConfig {
  config {
    auth {
      loginEnabled
      ssoEnabled
      ssoUrl
    }
  }
}

Best Practices

Use sessions for interactive applications: Session-based auth with MFA provides the best security for user-facing applications
Use API keys for integrations: Machine-to-machine communication should use API keys with appropriate scoping
Rotate credentials regularly: Implement key rotation policies for long-lived API keys
Handle session expiration gracefully: Check expiresAt and refresh or re-authenticate before expiration
Store credentials securely: Never commit credentials to version control; use environment variables or secret management systems
Monitor authentication events: Track authentication failures and unusual patterns

Next Steps

Quickstart Guide - Make your first authenticated query
Common Patterns - Learn about pagination and filtering
Domain Guides - Explore specific API capabilities

​Authentication

​Authentication Methods

​Session-Based Authentication

​Sign In

​Session Response

​Checking Current Session

​Sign Out

​Using Your Session

​1. Cookie Authentication (Browser/Web)

​2. Header Authentication (Machine-to-Machine)

​Multi-Factor Authentication (MFA)

​MFA Challenge Response

​Challenge Types

​Completing MFA Challenge

​API Key Authentication

​Creating an API Key

​Using API Keys

​AWS Credentials

​Getting AWS Credentials

​Using AWS Credentials

​Federated Sign-In (SSO)

​Session Management

​Session Expiration

​Switching User Groups

​Re-authentication

​Device Management

​Listing Devices

​Forgetting Devices

​Password Management

​Forgot Password

​Reset Password

​Authentication Configuration

​Best Practices

​Next Steps

Authentication

Authentication Methods

Session-Based Authentication

Sign In

Session Response

Checking Current Session

Sign Out

Using Your Session

1. Cookie Authentication (Browser/Web)

2. Header Authentication (Machine-to-Machine)

Multi-Factor Authentication (MFA)

MFA Challenge Response

Challenge Types

Completing MFA Challenge

API Key Authentication

Creating an API Key

Using API Keys

AWS Credentials

Getting AWS Credentials

Using AWS Credentials

Federated Sign-In (SSO)

Session Management

Session Expiration

Switching User Groups

Re-authentication

Device Management

Listing Devices

Forgetting Devices

Password Management

Forgot Password

Reset Password

Authentication Configuration

Best Practices

Next Steps