Newton Authentication: API Key & OAuth 2.0 Guide (2026)

Authentication overview

Newton provides an interactive notebook environment for mathematical computations and data visualization. The Newton API enables programmatic access to its core features, allowing external applications to interact with computational engines, manage notebooks, and automate workflows. Proper authentication is essential to ensure that only authorized entities can access and manipulate user data or system resources within the Newton ecosystem. The API design prioritizes secure communication and credential management to protect sensitive computational work and user accounts.

Authentication mechanisms for the Newton API are designed to accommodate different integration scenarios, from server-to-server communication to user-delegated access. Adherence to established security protocols helps maintain the integrity and confidentiality of data processed through the API. Developers should select the appropriate authentication method based on their application's specific requirements and security posture, always following best practices for credential handling and secure transmission over encrypted channels.

Supported authentication methods

The Newton API supports two primary authentication methods: API Keys and OAuth 2.0. Each method is suited for different integration patterns and provides distinct security and management characteristics.

API Keys provide a straightforward method for authenticating requests made directly by your applications. An API key is a unique string that identifies your project or account and grants access to the Newton API. These keys are typically generated from your Newton account dashboard (Newton homepage) and should be treated as sensitive credentials, similar to passwords.

OAuth 2.0 is an authorization framework that enables third-party applications to obtain limited access to a user's Newton account without exposing their credentials. This method is suitable for applications that need to interact with a user's notebooks or data on their behalf. OAuth 2.0 involves a client application requesting authorization from the user, who then grants or denies access. If granted, the client receives an access token, which it uses to make API requests (OAuth 2.0 specification overview). The Newton API implements standard OAuth 2.0 flows, typically the Authorization Code Grant flow, for web applications.

Getting your credentials

To begin authenticating requests to the Newton API, you need to obtain the appropriate credentials from your Newton account. The process varies slightly depending on whether you require an API key or plan to implement OAuth 2.0.

For API Keys:

1. Log In: Navigate to the Newton website and log into your account.
2. Access Settings: Go to your account settings or developer dashboard. Specific navigation might be labeled as 'API Settings', 'Developer Keys', or similar.
3. Generate Key: Look for an option to 'Generate New API Key' or 'Create Credential'. You may be prompted to provide a name for your key to help with organization and tracking.
4. Copy Key: Once generated, your API key will be displayed. Copy this key immediately and store it securely. Newton typically only displays the full key once, and you will not be able to retrieve it again if lost.
5. Key Rotation: Periodically rotate your API keys by generating a new one and revoking the old one to mitigate risks associated with compromised keys.

For OAuth 2.0:

1. Register Your Application: In your Newton developer dashboard, you must register your application. This process typically involves providing your application's name, a description, and most importantly, one or more Redirect URIs (callback URLs). The Redirect URI is where Newton will send the user back after they authorize your application.
2. Obtain Client ID and Client Secret: Upon successful application registration, Newton will provide you with a Client ID and a Client Secret. The Client ID identifies your application to Newton, and the Client Secret is a confidential credential used by your application to authenticate itself to Newton during the OAuth flow. Keep your Client Secret highly secure.
3. Define Scopes: When registering your application or initiating an authorization request, you will need to specify the OAuth scopes your application requires. Scopes define the specific permissions your application is requesting (e.g., read user notebooks, write computational data). Requesting only the necessary scopes adheres to the principle of least privilege, enhancing security.
4. Implement OAuth Flow: Integrate the standard OAuth 2.0 Authorization Code Grant flow into your application. This typically involves redirecting the user to Newton's authorization page, handling the callback at your Redirect URI, and exchanging the authorization code for an access token and refresh token. For a deeper understanding of OAuth 2.0 flows, refer to the RFC 6749 OAuth 2.0 Authorization Framework.

Authenticated request example

Once you have obtained your credentials, you can make authenticated requests to the Newton API. The method of including credentials in your request depends on the authentication type chosen.

Using an API Key:

For API key authentication, the key is typically sent in an HTTP header, commonly Authorization or a custom header specified by Newton, or as a query parameter. Newton documentation specifies using an X-Newton-Api-Key header for direct API access.

Example using curl:

curl -X GET \
  'https://api.newton.so/v1/notebooks' \
  -H 'X-Newton-Api-Key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json'

Replace YOUR_API_KEY_HERE with the actual API key generated from your Newton dashboard. This example fetches a list of notebooks associated with your account.

Using OAuth 2.0 Access Token:

After successfully completing the OAuth 2.0 flow, your application will receive an access_token. This token should be included in the Authorization header using the Bearer scheme for all subsequent API requests.

Example using curl:

curl -X POST \
  'https://api.newton.so/v1/computations' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{ "expression": "2 + 2" }'

Replace YOUR_OAUTH_ACCESS_TOKEN_HERE with the access token obtained through the OAuth flow. This example sends a computation request to the Newton API.

Security best practices

Adhering to security best practices is crucial when integrating with the Newton API to protect your data and maintain the integrity of your applications. Ignoring these practices can lead to unauthorized access, data breaches, and service disruptions.

• Secure Storage of Credentials: Never hardcode API keys or OAuth Client Secrets directly into your application's source code. Store them in environment variables, secure configuration files, or a dedicated secrets management service. For client-side applications (e.g., single-page applications), OAuth Client Secrets should only reside on the backend.
• Use HTTPS/TLS: Always ensure that all communication with the Newton API occurs over HTTPS (TLS 1.2 or higher). This encrypts data in transit, preventing eavesdropping and man-in-the-middle attacks. The Newton API enforces HTTPS for all endpoints.
• Principle of Least Privilege: When configuring API keys or requesting OAuth scopes, grant only the minimum necessary permissions required for your application to function. This limits the damage if a credential is compromised. Regularly review and adjust permissions as your application's needs evolve.
• API Key Rotation: Regularly rotate your API keys (e.g., every 90 days or if an employee leaves). This minimizes the window of vulnerability if a key is exposed. Newton's dashboard provides features to generate new keys and revoke old ones.
• OAuth Token Expiration and Refresh: OAuth access tokens have a limited lifespan. Your application should be designed to handle token expiration gracefully by using refresh tokens (if provided) to obtain new access tokens without requiring the user to re-authorize. Securely store refresh tokens, similar to API keys.
• Error Handling and Logging: Implement robust error handling for API authentication failures. Avoid logging sensitive credentials or tokens in plain text in your application logs. Log only necessary information for debugging, such as timestamps and non-sensitive error codes.
• Input Validation: Sanitize and validate all input that your application sends to the Newton API. This helps prevent injection attacks and ensures that requests are well-formed and legitimate.
• Rate Limiting and Abuse Detection: Be aware of Newton's API rate limits and design your application to handle them gracefully (e.g., using exponential backoff). Implement your own rate limiting for user-initiated actions to prevent abuse of your application that could lead to API key compromise or excessive usage.