Redivis API
User documentationredivis.com
  • Introduction
  • Referencing resources
  • Client libraries
    • redivis-js
      • Getting started
      • Examples
    • redivis-python
      • Getting started
      • Reference
        • redivis
          • redivis.current_notebook
          • redivis.file
          • redivis.organization
          • redivis.query
          • redivis.table
          • redivis.user
        • Dataset
          • Dataset.add_labels
          • Dataset.create
          • Dataset.create_next_version
          • Dataset.delete
          • Dataset.exists
          • Dataset.get
          • Dataset.list_tables
          • Dataset.list_versions
          • Dataset.query
          • Dataset.release
          • Dataset.remove_labels
          • Dataset.table
          • Dataset.unrelease
          • Dataset.update
          • Dataset.version
        • File
          • File.download
          • File.get
          • File.read
          • File.stream
        • Member
          • Member.add_labels
          • Member.exists
          • Member.get
          • Member.remove_labels
          • Member.update
        • Notebook
          • Notebook.create_output_table
        • Organization
          • Organization.dataset
          • Organization.list_datasets
          • Organization.list_members
          • Organization.member
        • Query
          • Query.download_files
          • Query.get
          • Query.list_files
          • Query.list_rows
          • Query.to_arrow_batch_iterator
          • Query.to_arrow_dataset
          • Query.to_arrow_table
          • Query.to_dataframe
          • Query.to_geopandas_dataframe
          • Query.to_dask_dataframe
          • Query.to_pandas_dataframe
          • Query.to_polars_lazyframe
        • Table
          • Table.add_files
          • Table.create
          • Table.delete
          • Table.download
          • Table.download_files
          • Table.get
          • Table.exists
          • Table.list_files
          • Table.list_rows
          • Table.list_uploads
          • Table.list_variables
          • Table.to_arrow_batch_iterator
          • Table.to_arrow_dataset
          • Table.to_arrow_table
          • Table.to_dataframe
          • Table.to_geopandas_dataframe
          • Table.to_dask_dataframe
          • Table.to_pandas_dataframe
          • Table.to_polars_lazyframe
          • Table.update
          • Table.upload
          • Table.variable
        • Upload
          • Upload.create
          • Upload.delete
          • Upload.exists
          • Upload.get
          • Upload.insert_rows
          • Upload.list_variables
          • Upload.to_*
        • Version
          • Version.dataset
          • Version.delete
          • Version.exists
          • Version.get
          • Version.previous_version
          • Version.next_version
        • User
          • User.dataset
          • User.list_datasets
          • User.workflow
          • User.list_workflows
        • Variable
          • Variable.get
          • Variable.exists
          • Variable.update
        • Workflow
          • Workflow.get
          • Workflow.exists
          • Workflow.list_tables
          • Workflow.query
          • Workflow.table
      • Examples
        • Listing resources
        • Querying data
        • Reading tabular data
        • Uploading data
        • Working with non-tabular files
    • redivis-r
      • Getting started
      • Reference
        • redivis
          • redivis$current_notebook
          • redivis$file
          • redivis$organization
          • redivis$query
          • redivis$table
          • redivis$user
        • Dataset
          • Dataset$create
          • Dataset$create_next_version
          • Dataset$delete
          • Dataset$exists
          • Dataset$get
          • Dataset$list_tables
          • Dataset$query
          • Dataset$release
          • Dataset$table
          • Dataset$unrelease
          • Dataset$update
        • File
          • File$download
          • File$get
          • File$read
          • File$stream
        • Notebook
          • Notebook$create_output_table
        • Organization
          • Organization$dataset
          • Organization$list_datasets
        • Query
          • Query$download_files
          • Query$get
          • Query$list_files
          • Query$to_arrow_batch_reader
          • Query$to_arrow_dataset
          • Query$to_arrow_table
          • Query$to_data_frame
          • Query$to_data_table
          • Query$to_tibble
          • Query$to_sf_tibble
        • Table
          • Table$add_files
          • Table$create
          • Table$delete
          • Table$download
          • Table$download_files
          • Table$get
          • Table$exists
          • Table$list_files
          • Table$list_uploads
          • Table$list_variables
          • Table$to_arrow_batch_reader
          • Table$to_arrow_dataset
          • Table$to_arrow_table
          • Table$to_data_frame
          • Table$to_data_table
          • Table$to_tibble
          • Table$to_sf_tibble
          • Table$update
          • Table$upload
          • Table$variable
        • Upload
          • Upload$create
          • Upload$delete
          • Upload$exists
          • Upload$get
          • Upload$insert_rows
          • Upload$list_variables
          • Upload$to_*
        • User
          • User$dataset
          • User$list_datasets
          • User$workflow
          • User$list_workflows
        • Variable
          • Variable$get
          • Variable$exists
          • Variable$update
        • Workflow
          • Workflow$get
          • Workflow$exists
          • Workflow$list_tables
          • Workflow$query
          • Workflow$table
      • Examples
        • Listing resources
        • Querying data
        • Reading tabular data
        • Uploading data
        • Working with non-tabular data
  • REST API
    • General structure
    • Authorization
    • Access
      • get
      • list
    • Datasets
      • delete
      • get
      • list
      • patch
      • post
    • Exports
      • download
      • get
      • post
    • Files
      • createSignedUrl
      • get
      • head
      • post
    • Members
      • get
      • list
    • Queries
      • get
      • post
      • listRows
    • ReadSessions
      • post
      • getStream
    • Tables
      • createTempUploads
      • delete
      • get
      • list
      • listRows
      • patch
      • post
    • Uploads
      • delete
      • get
      • insertRows
      • list
      • listRows
      • post
    • Variables
      • get
      • list
      • patch
    • Versions
      • delete
      • get
      • list
      • post
      • release
      • unrelease
    • Workflows
      • get
      • list
  • Resource definitions
    • Access
    • Dataset
    • Export
    • Member
    • Organization
    • Query
    • Table
    • Upload
    • User
    • Variable
    • Version
    • Workflow
Powered by GitBook
On this page
  • Overview
  • Scopes
  • Authentication mechanisms
  • OAuth
  • API Token
  • Using Access Tokens
  • Revoking access tokens
  • Export restrictions

Was this helpful?

  1. REST API

Authorization

PreviousGeneral structureNextAccess

Last updated 10 months ago

Was this helpful?

Overview

All requests to the Redivis API require an Authorization header in the HTTP request. In most cases, you should use the , , or client libraries to handle authentication and communication with the API. However, if you would like to interface with the REST API directly, you can either use OAuth or an API token to authenticate your API requests.

Scopes

When generating authorization credentials, you must specify the scopes associated with the credential. This allows you to control what actions any given token may perform. It is highly recommended to limit the scopes to the minimum necessary for your required functionality.

The following authorization scopes are available:

Scope
Description

public

This is the default scope, and is present on all tokens. It only allows access to resources on Redivis that are publicly available (e.g., if you were logged out).

Access tokens that only have the public scope can be safely shared with others, and are useful for building integrations that should only access public content (for example, surfacing Redivis datasets through your library's search engine).

data.overview

Allows for "overview" access to datasets that you can see but are hidden to the general public. This will reveal the dataset's existence and some documentation, but will not provide access to restricted variable names, summary statistics, or data.

data.metadata

Allows for "metadata" access to datasets whose metadata you can view but are hidden to the general public.

data.data

Allows for data access to a dataset's full tables (and their derivatives) when it is available to you but hidden to the general public.

data.edit

Allows you to create, edit, and delete datasets.

organization.read

Grants read-only access to administrative information about any organization that you are an administrator of.

organization.write

Grants the ability to change administrative information within your organizations, such as members' status and approvals.

Authentication mechanisms

OAuth

You can use OAuth to generate a short-lived API token for interfacing with the Redivis API. OAuth also supports the use case where you are building an application where you want users to authenticate using their Redivis account, to perform actions on behalf of that user. OAuth implementation is a complicated subject, and you should typically leverage established third-party libraries or integrations when developing your OAuth solution.

  • Authorization URL:

  • Client ID, Client Secret: Leave these blank for most use cases. Without a client ID, the access token return via OAuth will be short-lived, and is generally only intended for use during a given session. If you need to store a user's OAuth token for offline use, please contact us to register your application and generate client credentials.

API Token

When you create a token, you will have the ability to name it and grant it specific scopes; the scopes and name can be modified later. When the token is created, you will be able to see the actual token just once — store it in a secure place for future use.

IMPORTANT: API tokens operate like passwords, and a compromised token can allow another party to access resources on your behalf.

You should never share sensitive tokens, and avoid committing to source control where collaborators may have access (either now or in the future). Always make sure to limit your token scopes to those that are necessary for them to function.

Using Access Tokens

In order to interact with the REST API, you will need to provide your token (either derived from the OAuth flow or your API token) in the header of your HTTPS request. Set the token in the Authorization request header with the value Bearer ACCESS_TOKEN .

curl -i -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    https://redivis.com/api/v1/organizations/demo/datasets

If you are leveraging one of the client libraries, you can instead set the env variable REDIVIS_API_TOKEN to your token.

export REDIVIS_API_TOKEN=your_access_token

Revoking access tokens

If you have lost an access token, are no longer using it, or if you have reason to believe your access token has been compromised, it is important that you revoke it. Navigate to your workspace settings and press the "revoke" button next to the token in question.

Export restrictions

Some datasets on Redivis have export restrictions that limit the number of bytes, records, or ip address(es) for data egress. If your request is in conflict with any of these restrictions (for example, your ip address is not in the export whitelist) the API method will return a 403 Not authorized .

These restrictions only apply to actual data content — for example, when reading tables or executing queries.

Redivis supports two types of OAuth flows: the , where a user is authenticating on the same device they are using to make a request, as well as the , allowing the user to authenticate one device from another, for the scenario where the authenticating device doesn't have access to a browser.

Both flows require the use of the additional with the S256 (sha256) code_challenge_method.

(standard flow)

(device authorization flow)

Token URL:

Scope: The relevant (e.g., data.metadata). You should always request the minimum necessary for your application to function.

To create long-lived API tokens (e.g., for non-interactive services that continuously interact with the API), you can generate an API token on your workspace. Navigating to your to create a new token.

standard authorization flow
device authorization flow
PKCE security layer
https://redivis.com/oauth/authorize
https://redivis.com/oauth/device_authorization
https://redivis.com/oauth/token
Workspace -> Settings -> API tokens
Python
R
Javascript
appropriately set
access scope
Generate tokens from your workspace