Gravity
  • Welcome to Gravity
  • Getting Started
  • Stack
  • Updates
  • Rules For AI
  • Troubleshooting
  • Gravity Server
    • Introduction
    • Installation
      • Install Node.js
      • Database Setup
      • Stripe Setup
      • Mailgun Setup
      • Install Gravity
    • Application Structure
    • REST API
      • API Scopes
      • Webhooks
    • Authentication
      • Email Verification
      • Social Sign On
      • Two-Factor Authentication
    • Authorization
      • Feature Access and Plan Restrictions
      • Permissions (Roles)
    • Config
    • Environment Variables
    • Database Queries
    • Handling Errors
    • Logging
    • Localization
    • Push Notifications
    • Email Notifications
    • User Feedback
    • User Onboarding
    • File Uploads
    • Billing
      • Seat Billing
      • Usage Billing
    • Free Accounts
    • CLI Toolbelt
    • Testing
    • AI Tools
    • Background Jobs
    • Deployment
  • Gravity Web
    • Introduction
    • Tailwind & SCSS
    • Routing
    • Events
    • Authentication
    • Localization
    • Hooks
      • useAPI
      • usePlans
      • usePermissions
    • Components
      • Alert
      • Animate
      • Avatar
      • Badge
      • Breadcrumb
      • Button
      • Calendar
      • Card
      • Chart
      • Checklist
      • Credit Card
      • Detail
      • Dialog
      • Dropdown
      • Feedback
      • Form
      • Grid
      • Header
      • Helper
      • Icon
      • Image
      • Layout
      • Link
      • List
      • Loader
      • Logo
      • Nav
      • Onboarding
      • Pagination
      • Popover
      • Progress
      • Row
      • Search
      • Separator
      • Sheet
      • Social
      • Stat
      • Table
      • Tabs
      • Toast (Notification)
      • Tooltip
      • User
      • View
    • Views
    • Handling Errors
    • Deployment
  • Gravity Native
    • Introduction
    • Prerequisites
    • Installation
    • App Context
    • Authentication
    • Localisation
    • External Linking
    • Handling Errors
    • Navigation
    • Config
    • Events
    • Views
    • Components
      • Badge
      • Blankslate
      • Button
      • Card
      • Chart
      • Form
      • Global
      • Grid
      • Icon
      • List
      • Logo
      • Message
      • Modal
      • Nav
      • Notification
      • Progress Bar
      • Search
      • Separator
      • Social
      • Stat
      • View
    • Push Notifications
    • Payments
    • Building Your App
  • Mission Control
    • Introduction
    • Installation
    • User Management
    • Feedback
    • Events
    • Logs
  • Website Template
    • Introduction
    • Environment Variables
    • Styling
    • Components
      • Article
      • Feature List
      • Footer
      • Hero
      • Layout
      • Pricing
      • Meta Data
      • Nav
      • Testimonial
    • Build and Deploy
Powered by GitBook
On this page
  • Protected Routes
  • Accessing The API
  • Using Bearer Tokens
  • Using API Keys
  • Input Validation
  • Rate Limiting
  • API Logs
  • Swagger File

Was this helpful?

  1. Gravity Server

REST API

PreviousApplication StructureNextAPI Scopes

Last updated 7 months ago

Was this helpful?

Both and communicate with Gravity Server using a REST API.

The API files are located in the /api folder.

The structure of these files is simple; there is a list of endpoints that connect directly to the relevant controller method.

api.post('/api/account', use(accountController.create));

Protected Routes

You can protect any API route and make it accessible to only a specific user level or API key scope using the auth.verify middleware method. You simply pass the user permission as the first argument, and an optional API scope as the second.

// protect using a user permission
api.get('/api/user', auth.verify('user'), use(userController.get));

// protect using a user permission and api scope
api.get('/api/user', auth.verify('user', 'account.read'), use(userController.get));

Accessing The API

You can access the API using one of two methods:

  1. Using an API key

Using Bearer Tokens

Bearer tokens are JWTs that are used to authenticate the user. You can use a Bearer token with the API by passing it in the Authorization header.

Bearer your_jwt

Using API Keys

API keys can be created by either an owner or developer permission and can be used to access any endpoint that has an API scope (see Protected Routes above).

API keys are stored in the database in plain text to remove the decryption overhead on each API call, and so the user can retrieve an API key if they lose it. For most applications this is acceptable, if your database is breached and the API keys are stolen, an attacker already has access to all of your data, so encryption provides minimal protection in this scenario.

The following example demonstrates how to make an API request in Javascript with the Axios package and Basic authentication.

const res = await axios({

  url: 'https://yourdomain.com/api/user'
  method: 'POST',
  data: {
    email: 'kyle',
    password: 'test1'
  },
  headers: {
    Authorization: 'Basic YOUR_API_KEY'
  },
});

Input Validation

// validate
const data = utility.validate(joi.object({
    
    email: joi.string().email().required(),
    name: joi.string().required().min(3).max(100),
    password: joi.string().required().pattern(new RegExp(config.get('security.password_rules'))),
    confirm_password: joi.string().allow(null),
    verify_view_url: joi.string().allow(null)

}), req, res);

Rate Limiting

  • POST /api/account

  • POST /api/user

  • POST /api/user/auth

  • POST /api/user/password/reset/request

  • POST /api/user/password/reset

API Logs

Every API request is logged in the log table by default. You can toggle this on or off using the ENABLE_API_LOGS environment variable.

ENABLE_API_LOGS=true

Swagger File

There is a swagger file included in api/spec.yaml with documentation and examples for each endpoint using the OpenAPI 3.0 spec. You can import this into Postman for easy testing.

Each controller call is wrapped in a HOC (higher-order component) called use. This is a middleware function that catches any errors in the controller methods and then passes these to a global – this prevents you from having to use try...catch in your application.

Learn more about and find out more about how authentication works in the

Using a Bearer token issued during the flow

Input validation is handled with JOI, which has been wrapped in a HOF to support .

API requests are globally rate-limited as defined by the throttle settings in . The following end points have their own lower rate limits for security purposes:

error handler
API scopes
next section.
authentication
locales
config
Gravity Web
Gravity Native