---
# System prepended metadata

title: Getting Started with the Ridge API

---

---
title: "Getting Started with the Ridge API"
slug: "getting-started-1"
hidden: false
createdAt: "2020-12-03T14:42:48.952Z"
updatedAt: "2021-01-11T12:01:55.910Z"
---
# Introduction
This guide explains the core concepts necessary for working with the Ridge API.

# API Token
The Ridge API is a RESTFUL API that uses JSON encoding. All API requests must include a token in the header for authentication. The token is obtained using the Ridge API, and placed in the HTTP Authorization request header.

 Authorization: Bearer <Token>
     
# API Variables - Quantities and Qualities
In some cases, the input or output fields for an API function are defined as variables named Quantities and Qualities. In these cases, the definition of the variable appears at the bottom of the page that describes the function. (This is, as opposed to the description of non-variable parameters that appear inline.)

# Resource Management
Ridge resources are managed with a hierarchical structure.  
  * Orgs and Projects are used for grouping and managing resources. 
  * Groups are used for conveniently managing access to resources. 

## Orgs
Organizations (Orgs) are the top level of the hierarchy and provide Ridge customers with full visibility of all consumed resources and the ability to segment and manage resources including user management and account administration.  Each customer is associated with at least one Org.  

## Projects
Projects are part of an Organization.  Projects provide the ability to logically segment resources within an Org.  Projects contain infrastructure resources, (Compute, Network and Storage) that are consumed using Ridge Services.  User and/or groups may be granted roles in each project.


## Resource Identifiers 
Ridge resources can be identified by:

* **name** - a unique identifier for the resource which can be configured by the user. 

* **ID** -  a unique identifier generated by Ridge and which should not be changed.

## Resource Access Examples
In the examples below we perform all the requests in an org named **test-org** and a project named **test-proj**.

### Access a Resource by Member Name
GET  https://api.ridge.co/iam/v1alpha/orgs/example-org/members/my-name
### Access a Resource by ID (prepended by  `@`)
GET  https://api.ridge.co/iam/v1alpha/orgs/example-org/members/@4536
### Access All Resources 
To access all resources, include`-`  in the path as shown in the example below.
For example, to get the list of members of all groups:
GET https://api.ridge.co/iam/v1alpha/orgs/example-org/groups/-/members

**Note:** The API version in the examples throughout this document is set to **v1alpha**. 

Parameters in the JSON body with the suffix  **_path** should be set with the part of the resource’s path that follows the API version.

# Display Name
Each Ridge resource can have an optional **display_name** that is used only for display in the Console.

Upon resource creation, the **display_name**, by default, is equal to the name.

The **display_name** may include up to 512 Unicode characters, including up to 64 lowercase Latin letters, numbers or dashes.