Apps & API Keys

Go to Apps in the Developer section to manage apps and API keys.

API Keys

API keys provide programmatic access to workspace data. Use them for scripts, integrations, or external services that need to read or write data.

Creating an API Key

1. Go to Apps → API Keys tab
2. Click Create API Key
3. Configure:

4. Click Create
5. Copy the key immediately - it won't be shown again

Using API Keys

Include the key in the Authorization header:

bash

Revoking Keys

Click the revoke button next to any key to immediately invalidate it. Revoked keys cannot be restored.

Webhook Secret

The Apps page also shows your Webhook Secret for verifying incoming webhook payloads. See Webhooks for details.

---

Apps (OAuth)

Gravity Rail Apps allow third-party tools and services to integrate with Gravity Rail workspaces using OAuth.

Key Concepts

Member-Based Grants

In Gravity Rail, Apps don't store long-lived access tokens. Instead:

• Members grant permissions to applications within their workspaces (AppGrants)
• Tokens are generated dynamically when needed
• Two-layer encryption protects sensitive data
• Shared grants allow workspace-wide access (admin only)

Client Credentials

Each Application has:

• Client ID: A public identifier for your application (format: gr_app_xxxxx)
• Client Secret: A base64url-encoded 16-byte key for decrypting tokens (only shown once)
• Encrypted Tokens: Dynamically generated tokens with member context

Available Scopes

Scopes define permissions for things Workspace members can do with the app:

Account Scopes

• account:read - Read account information
• account:write - Update account information
• account:create - Create new accounts (dangerous)

Workspace Scopes

• workspace:read - Read workspace information and settings
• workspace:write - Update workspace settings
• workspace:delete - Delete workspaces (dangerous)

Member Scopes

• members:read - Read member information
• members:write - Update member information
• members:admin - Full member management (dangerous)

Task Scopes

• task:read - Read task configurations
• task:write - Create and update tasks
• task:delete - Delete tasks
• task:execute - Execute tasks and manage assignments

Data Scopes

• data:read - Read data types and records
• data:write - Create and update data records
• data:delete - Delete data records
• data:admin - Full data management including schema changes (dangerous)

Chat Scopes

• chats:read - Read chat messages and history
• chats:write - Send messages and create chats
• chats:admin - Manage all chats

Agent Scopes

• assistants:read - Read agent configurations
• assistants:write - Create and update agents
• assistants:admin - Full agent management

Workflow Scopes

• workflows:read - Read workflow configurations
• workflows:write - Create and update workflows
• workflows:delete - Delete workflows

Site Scopes

• sites:read - Read site configurations and pages
• sites:write - Create and update sites and pages
• sites:publish - Publish sites and manage domains

Export Scopes

• export:read - Export workspace data
• export:read-all - Export all workspace data including sensitive information (dangerous)

Admin Scope

• admin:superuser - Full system administration (dangerous)

Creating an App

Via the Web Interface

1. Navigate to Settings → Apps
   • If you haven't already, create a "Builder" profile from the "Builder Profiles" tab
2. Click Create App
3. Fill in the application details:
   • Name: A descriptive name for your application
   • Description: Optional description of what the application does
   • Workspace Restrictions: Optionally limit the app to specific workspaces
   • Builder Profile: Select the builder profile you'd like to associate with the app
4. Click Create Application
5. Important: Copy and securely store the client secret - it will only be shown once!

Application Settings

When creating or editing an application, you can configure:

• Name and Description: Identify your application
• Workspace Restrictions: Limit the application to specific workspace UUIDs
• Active Status: Enable or disable the application

Note: Scopes are NOT configured at the application level. They are specified when members create grants.

How Apps Work

1. Member Authorization

Workspace members grant permissions to Apps by creating AppGrants:

• Personal grants: Accessible only by the member who created them
• Shared grants: Workspace-wide access (requires admin permissions)

2. Token Generation

When an Application needs access:

1. Gravity Rail generates an encrypted token containing member context
2. The token uses two-layer encryption:
   • Inner layer: API token encrypted with system secret (opaque to OAuth app)
   • Outer layer: Wrapper encrypted with client secret (decryptable by OAuth app)
3. Token format: gr_app_<client_id>:<encrypted_payload>

3. Using Encrypted Tokens

Apps decrypt the outer layer to access the API token:

python

Managing Apps

Viewing Apps

1. Go to Settings → Apps
2. View all your applications in the data table
3. See status and creation details

Viewing Credentials

1. Click the Key icon next to an application
2. View the Client ID (always visible)
3. Client Secret is only shown once during creation

Editing Apps

1. Click the Edit icon next to an application
2. Update name, description, or status
3. Add or remove workspace restrictions
4. Click Save Changes

Regenerating Client Secret

If your client secret is compromised:

1. Click the Refresh icon next to the application
2. A new client secret will be generated
3. Copy and store the new secret securely
4. Update your integrations with the new secret
5. The old secret immediately becomes invalid

Deleting Apps

1. Click the Delete icon next to an application
2. Confirm the deletion
3. All associated AppGrants will be invalidated
4. Any integrations using this application will stop working

Member Grants (AppGrants)

Creating Grants

Members create grants to authorize Apps in their workspaces:

1. The application requests specific scopes
2. The member reviews and approves permissions
3. An AppGrant is created with the approved scopes
4. Tokens can now be generated for this grant

Shared Grants

Workspace administrators can create shared grants:

• Provide workspace-wide access to all members
• Only one shared grant per application per workspace
• Requires manage_workspace permission
• Useful for common tools used by entire teams

Revoking Grants

Members can revoke grants at any time:

1. Navigate to workspace settings
2. View active AppGrants
3. Revoke specific grants
4. Tokens for revoked grants immediately become invalid

Best Practices

Security

1. Never expose client secrets in client-side code or public repositories
2. Store credentials securely using environment variables or secret management systems
3. Rotate secrets regularly especially if there's any suspicion of compromise
4. Request minimum required scopes when creating grants
5. Monitor grant usage for suspicious activity
6. Use HTTPS only when making API requests
7. Handle token expiry gracefully (tokens are short-lived)

Implementation

1. Understand two-layer encryption for proper token handling
2. Decrypt tokens correctly using the client secret
3. Handle grant revocation gracefully in your application
4. Log authentication events for debugging and auditing
5. Respect member permissions and scope limitations

Organization

1. Use descriptive names for applications to identify their purpose
2. Document integration details including which systems use which applications
3. Separate applications by environment (development, staging, production)
4. Restrict workspace access when applications only need specific workspace access
5. Regularly audit your Apps and remove unused ones

MCP Server Integration

The Gravity Rail MCP (Model Context Protocol) server supports OAuth authentication:

bash

Integration Examples

Python (OAuth Application)

python

JavaScript/TypeScript (OAuth Application)

typescript

Troubleshooting

Decryption Failed

Problem: Cannot decrypt the token's outer layer

Solutions:

• Verify the client secret is correct (base64url-encoded 16-byte key)
• Ensure proper base64url decoding (may need padding)
• Check you're using the correct encryption algorithm (A128GCM)

Grant Not Found

Problem: Token generation fails with grant not found

Solutions:

• Verify the member has created an AppGrant for your application
• Check the grant hasn't been revoked
• Ensure the requested scopes match the granted scopes
• For shared grants, verify the creator had admin permissions

Token Expired

Problem: Getting 401 Unauthorized errors

Solutions:

• Tokens are short-lived (5 minutes for MCP)
• Request new tokens as needed
• Don't cache tokens for extended periods

Workspace Access Denied

Problem: Getting 403 Forbidden for workspace operations

Solutions:

• Check if the application has workspace restrictions
• Verify the member has access to the workspace
• Ensure the AppGrant is for the correct workspace
• Check scope permissions match the operation

Key Differences from Traditional OAuth

1. No Token Exchange: No /token endpoint - tokens generated via AppGrants
2. Member-Based: Permissions granted by workspace members, not accounts
3. Two-Layer Encryption: Nested encryption for enhanced security
4. Dynamic Generation: Tokens created on-demand, not stored
5. Grant-Level Scopes: Scopes defined when creating grants, not applications

Support

For additional help with Apps, contact support for assistance with specific issues.