Authentication & Login

Maeris MCP uses OAuth2-based authentication to securely connect your local CLI to the Maeris platform. Once authenticated, your credentials are stored locally and reused automatically for all subsequent commands and MCP tool calls.

Logging In

To authenticate with Maeris, run the login command from anywhere in your terminal:

maeris auth login

This opens a browser window pointing to the Maeris OAuth2 authorization page. Sign in with your Maeris account (Google SSO or email/password), grant the requested permissions, and the browser will redirect back. The CLI captures the token automatically — no copy-pasting required.

Headless environments

If you are running in a server or CI environment without a browser, the CLI will print a one-time authorization URL. Open it on another device, complete the login, and the token will be delivered to your CLI session via a local callback server.

Checking Authentication Status

To confirm you are authenticated and see which account is active:

maeris auth status

Example output when authenticated:

Authenticated as: alex@example.com
Application: my-web-app
Scope: full
Token expires: 2026-06-01

Logging Out

To revoke your local token and log out:

maeris auth logout

This removes the stored token from your local machine. You will need to run maeris auth login again to re-authenticate.

Access Scopes

Maeris supports three permission scopes for MCP tool access:

read — View collections, tests, environments, and scan results. No modifications allowed.
write — Create, update, and delete resources. Cannot run security scans or manage team settings.
full — Complete access including security scans, CI/CD integration, and team management.

To change the scope for your current application, use:

maeris app scope <read|write|full>

For example, to grant full access:

maeris app scope full

Scope changes require re-authentication.

After changing the scope, run maeris auth login again to obtain a new token that includes the updated permissions.

Token Storage

Your authentication token is stored securely in a local configuration directory on your machine. Maeris uses your operating system's standard user config location:

macOS: ~/.config/maeris/credentials.json
Linux: ~/.config/maeris/credentials.json
Windows: %APPDATA%\maeris\credentials.json

The token is never committed to your repository. The .mcp.json file contains only server launch configuration, not credentials.

Troubleshooting Auth Issues

If you encounter authentication errors, try the following steps:

# Check current auth status maeris auth status # Re-authenticate maeris auth logout maeris auth login # Run full diagnostics maeris doctor

For more diagnostic help, see the Diagnosing Setup Issues guide. To revisit the project setup, see Initialize Your Project.