Authentication

Parascope supports two authentication methods: Single Sign-On (SSO) via OIDC for interactive users, and API tokens for programmatic access.

Single Sign-On (SSO)

When SSO is enabled, you can log in using your organization's identity provider (Okta, Azure AD, Google, and other OIDC-compatible providers).

Logging In

1. Navigate to Parascope
2. Click Sign in with SSO
3. Authenticate with your identity provider
4. You'll be redirected back to Parascope, now logged in

Your user account is created automatically on first login (Just-In-Time provisioning). The account inherits your name and email from the identity provider.

Session Management

Sessions are valid for 24 hours by default. Your session automatically refreshes when you're actively using Parascope. If your session expires, you'll be redirected to the login page.

To log out, click your user avatar in the top-right corner and select Sign out.

API Tokens

API tokens allow programmatic access to Parascope. Tokens inherit your permissions and data scopes, so they can only access what you can access.

Creating a Token

1. Click your user avatar and select API Tokens
2. Click Create Token
3. Enter a name and description
4. Select an expiration period
5. Click Create

Important: Copy your token immediately. It will only be shown once.

Using a Token

Include your token in the X-API-Key header:

curl -H "X-API-Key: ps_usr_your_token_here" \
  https://your-company.parascope.io/api/v1/configuration-items

Token Limits

• Maximum 10 tokens per user
• Maximum expiration: 1 year
• Tokens can be revoked at any time

Revoking a Token

1. Click your user avatar and select API Tokens
2. Find the token you want to revoke
3. Click Revoke
4. Confirm the revocation

Revocation is immediate. Any requests using the revoked token will fail.

Permissions and Data Scopes

Your access to Parascope resources is controlled by:

1. Permissions: What actions you can perform (read, write, delete)
2. Data Scopes: Which data you can see (by source and instance)

How Permissions Work

Permissions are assigned either directly to you or through team membership. Your effective permissions are the union of:

• Direct permissions assigned to your user
• Permissions from all teams you belong to

For example, if Team A grants read on configuration items and Team B grants write, you'll have both read and write access.

How Data Scopes Work

Data scopes restrict which CIs you can see. Scopes are defined by:

• Source: The data source (kubernetes, proxmox, ceph, etc.)
• Scope ID: A specific cluster or instance within that source

Like permissions, your effective data scopes are the union of your direct scopes and team scopes.

Example scopes:

Superadmin

Superadmin users bypass all permission and scope checks. They have full access to everything in Parascope.

Token Security Best Practices

1. Use descriptive names: Name tokens by their purpose (e.g., "GitHub Actions CI")
2. Set appropriate expiration: Use the shortest expiration that meets your needs
3. Rotate regularly: Create new tokens and revoke old ones periodically
4. Don't share tokens: Each person or system should have their own token
5. Use environment variables: Never hardcode tokens in scripts or code

# Good: Use environment variable
export PARASCOPE_TOKEN="ps_usr_..."
curl -H "X-API-Key: $PARASCOPE_TOKEN" ...

# Bad: Hardcoded token
curl -H "X-API-Key: ps_usr_abc123..." ...

Troubleshooting

"Authentication required" error

You're trying to access a protected resource without a valid session or token.

• Browser: Log in via SSO
• API: Include a valid X-API-Key header

"Permission denied" error

You don't have permission for the requested action. Check with your administrator to ensure you have the appropriate permissions.

"No data found" when you expect results

Your data scopes may not include the source you're querying. Check your effective scopes in your user profile (click your avatar, then Profile).

Token stopped working

• The token may have expired
• The token may have been revoked
• Your user account may have been deactivated

Click your avatar and select API Tokens to check your token status.