Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

API

Christian Smith edited this page · 33 revisions
Clone this wiki locally

Making REST API Requests

All REST API requests require HTTP Basic authentication with administration credentials.

GET

$ curl -v --user KEY:SECRET https://HOST:PORT/v1/RESOURCE

GET

$ curl -v --user KEY:SECRET https://HOST:PORT/v1/RESOURCE/ID

POST

$ curl -X POST --user ID:SECRET \
       -H 'Content-type: application/json' \
       -d '{...}' \
       https://HOST:PORT/v1/RESOURCE

PUT

$ curl -X PUT --user ID:SECRET \
       -H 'Content-type: application/json' \
       -d '{...}' \
       https://HOST:PORT/v1/RESOURCE/ID

PATCH

$ curl -X PATCH --user ID:SECRET \
       -H 'Content-type: application/json' \
       -d '{...}' \
       https://HOST:PORT/v1/RESOURCE/ID

DELETE

$ curl -X DELETE --user ID:SECRET \
       https://HOST:PORT/v1/RESOURCE/ID

REST Resources

Accounts

Routes

GET    /v1/accounts
GET    /v1/accounts/:id
POST   /v1/accounts
PUT    /v1/accounts/:id
PATCH  /v1/accounts/:id
DELETE /v1/accounts/:id

Schema

{
  name:       { type: 'string' },
  email:      { type: 'string', required: true, format: 'email' },
  password:   { type: 'string' } // stored as a hash
}

Account Groups

Routes

GET    /v1/accounts/:accountId/groups
PUT    /v1/accounts/:accountId/groups/:groupId
DELETE /v1/accounts/:accountId/groups/:groupId

Account Roles

Routes

GET    /v1/accounts/:accountId/roles
PUT    /v1/accounts/:accountId/roles/:roleId
DELETE /v1/accounts/:accountId/roles/:roleId

Apps

A Client is a registered application that initiates authorization grants from OAuth2Server.

GET    /v1/apps
GET    /v1/apps/:id
POST   /v1/apps
PUT    /v1/apps/:id
PATCH  /v1/apps/:id
DELETE /v1/apps/:id

Schema

{
  type:        { type: 'string', required: true, enum: ['confidential', 'public', 'trusted'] },
  name:        { type: 'string' },
  website:     { type: 'string' },
  description: { type: 'string' },
  logo:        { type: 'string' },
  terms:       { type: 'boolean' },
  secret:      { type: 'string' }
}

App Groups

Routes

GET    /v1/apps/:appId/groups
PUT    /v1/apps/:appId/groups/:groupId
DELETE /v1/apps/:appId/groups/:groupId

Groups

Routes

GET    /v1/groups
GET    /v1/groups/:id
POST   /v1/groups
PUT    /v1/groups/:id
PATCH  /v1/groups/:id
DELETE /v1/groups/:id

Schema

{
  name: { type: 'string' }
}

Group Accounts

Routes

GET    /v1/groups/:groupId/accounts
PUT    /v1/groups/:groupId/accounts/:accountId
DELETE /v1/groups/:groupId/accounts/:accountId

Group Apps

Routes

GET    /v1/groups/:groupId/apps
PUT    /v1/groups/:groupId/apps/:appId
DELETE /v1/groups/:groupId/apps/:appId

Roles

Routes

GET    /v1/roles
GET    /v1/roles/:id
POST   /v1/roles
PUT    /v1/roles/:id
PATCH  /v1/roles/:id
DELETE /v1/roles/:id

Schema

{
  name: { type: 'string' }
}

Role Accounts

Routes

GET    /v1/roles/:roleId/accounts
PUT    /v1/roles/:roleId/accounts/:accountId
DELETE /v1/roles/:roleId/accounts/:accountId

Role Scopes

Routes

GET    /v1/roles/:roleId/scopes
PUT    /v1/roles/:roleId/scopes/:scopeId
DELETE /v1/roles/:roleId/scopes/:scopeId

Scopes

Routes

GET    /v1/scopes
GET    /v1/scopes/:id
POST   /v1/scopes
PUT    /v1/scopes/:id
PATCH  /v1/scopes/:id
DELETE /v1/scopes/:id

Schema

{
  url:         { type: 'string', required: true, format: 'url' },
  description: { type: 'string', required: true },
  serviceId:   { type: 'string', required: true }
}

Scope Roles

Routes

GET    /v1/scopes/:scopeId/roles
PUT    /v1/scopes/:scopeId/roles/:roleId
DELETE /v1/scopes/:scopeId/roles/:roleId

Services

A "Service" is a registered server with resources protected by OAuth2Server.

GET    /v1/services
GET    /v1/services/:id
POST   /v1/services
PUT    /v1/services/:id
PATCH  /v1/services/:id
DELETE /v1/services/:id

Schema

{
  uri:         { type: 'string', required: true },
  secret:      { type: 'string', required: true },
  description: { type: 'string' }
}

Service Scopes

Routes

GET    /v1/services/:serviceId/scopes
POST   /v1/services/:serviceId/scopes

Obtaining Authorization

Resource Owner Password Credentials Grant

Client credentials are included in the Authorization header as a base64 encoded string. The remainder of the parameters are www-form-urlencoded in the request body.

$ curl -X POST --user CLIENT_ID:CLIENT_SECRET \
       -d 'grant_type=password&username=EMAIL&password=PASSWORD&scope=SCOPE' \
       'https://HOST:PORT/token'

Access Token Validation

Protected resource servers can validate an access token against OAuth2Server by including HTTP Basic credentials for the registered resource and www-form-urlencoded token and scope parameters in the body.

$ curl -X POST --user RESOURCE_ID:RESOURCE_SECRET \
       'https://HOST:PORT/access' \
       -d 'access_token=TOKEN&scope=SCOPE'
Something went wrong with that request. Please try again.