RemoteAuth

API

Overview

RemoteAuth provides a JSON REST API for its users. Applications must authenticate via the OAuth 2.0 protocol, see Authentication for more information.

Nearly all functionality provided by RemoteAuth is accessible via the API:

  • Application endpoints
  • Team endpoints
  • Application Member endpoints
  • Role endpoints
  • Permission endpoints

Authentication

Before continuing, you should be familiar with the OAuth 2.0 protocol.

There are two types of authorization grants available: Authorization Code Grant and Implicit Grant.

Authorization Code Grant

The Authorization Code Grant is used when the client (in this case, your application) is capable of securely storing its secret token. If your client cannot securely store your secret token, you should use the Implicit Grant instead.

There are four steps involved when using the Authorization Code Grant:

  1. Make a request to get an authorization code. If approved, RemoteAuth will make a request back to the redirect_uri provided:

Endpoint: /oauth/authorize

Request method: GET

Request parameters:

  • client_id - Identifier of your OAuth Client, created in RemoteAuth.
  • redirect_uri - Redirect URL that RemoteAuth should redirect the user to during the OAuth workflow.
  • response_type - "code"
  • scope - The comma delimited list of requested scopes for the authorization.
  1. Handle the redirect from RemoteAuth. Make sure your application can receive a GET request at the URL you provided in the redirect_uri of the previous step.

RemoteAuth will send the authorization code back as the code query parameter:

https://example.com/callback?code=auth_code_is_here
  1. After obtaining the authorization code, you can make a POST request to RemoteAuth to convert it into an access token.

Endpoint: /oauth/token

Request method: POST

Request parameters:

  • client_id - Identifier of your OAuth Client, created in RemoteAuth.
  • client_secret - The secret of your OAuth Client, created in RemoteAuth.
  • grant_type - "authorization_code"
  • redirect_uri - Redirect URL that RemoteAuth should redirect the user to during the OAuth workflow.
  • code - The authorization code passed during the redirect in the previous step.

If your request is valid, RemoteAuth will respond to the request with the following:

{
    "access_token": "XXXXX",
    "refresh_token": "XXXXX",
    "expires_in": 120
}
  • access_token is the access token that can be used to authenticate your API request to RemoteAuth (on behalf of the user).
  • refresh_token is the refresh token that can be used to request a new access token.
  • expires_in is the number of seconds until the access token expires.
  1. Refresh the access token once it expires. After the expires_in number of seconds passes, the access token will expire. You can use the refresh token to get a new access token:

Endpoint: /oauth/token

Request method: POST

Request parameters:

  • client_id - Identifier of your OAuth Client, created in RemoteAuth.
  • client_secret - The secret of your OAuth Client, created in RemoteAuth.
  • grant_type - "refresh_token"
  • refresh_token - The refresh token that was returned when the access token was granted.
  • scope - The comma delimited list of requested scopes for the authorization.

The response to this request be will the same payload as when we obtained an access token previously:

{
    "access_token": "XXXXX",
    "refresh_token": "XXXXX",
    "expires_in": 120
}
  1. Use the access token to make requests. When making requests to RemoteAuth, pass the access token via the Authorization header:
"headers": {
    "Authorization": "Bearer ACCESS_TOKEN_HERE"
}

Implicit Grant

TODO

Scopes

TODO

Resources

The following resources are returned from the API. The Endpoints section of the documentation will make reference to these resources.

Access Token Resource

id | string | The identifier of the Access Token.

user_id | string | The identifier of the User the Access Token belongs to.

client_id | string | The identifier of OAuth Client the Access Token grants access to.

client_name | string | The name of the OAuth Client the Access Token grants access to.

name | string | The name of the Access Token.

scopes | array | Array of scopes the Access Token has access to.

revoked | boolean | Indicates if the Access Token is revoked.

expires_at | string | Date/time string of when the Access Token will expire.

created_at | string | Date/time string of when the Access Token was created.

Example payload:

{
    "id": "XXXXX",
    "user_id": "XXXXX",
    "client_id": "XXXXX",
    "client_name": "Sample Client Name",
    "name": "Sample Token Name",,
    "scopes": ["sample-scope", "fake-scope"],
    "revoked": false,
    "expires_at": "2020-01-01 00:00:00",
    "created_at": "2019-01-01 00:00:00"
}

Application Resource

id | string | Identifier of the Application.

name | string | Name of the Application.

allows_registration | boolean | Indicates if the Application allows public user registration.

application_type | string | Type of Application, either "user" or "team".

url | string | The URL of the Application.

webhook | string | The webhook URL of the Application called by RemoteAuth when events happen.

application_members_count | integer | The number of Application Members attached to this Application.

owner_team | Team | The Team resource who owns the Application.

Example payload:

{
    "id": "XXXXX",
    "application_members_count": 98,
    "name": "RemoteAuth",
    "owner_team": { ... },
    "url": "http://remoteauth.com",
    "webhook": "http://remoteauth.com/webhook",
    "allows_registration": true,
    "application_type": "user"
}

Application Member Resource

id | string | The identifier of the ApplicationMember.

application_id | string | The identifier of the Application that the ApplicationMember is attached to.

created_at | string | The date/time that the ApplicationMember record was created at.

team | Team | Optional. The Team the ApplicationMember is attached to.

user | User | The User the ApplicationMember belongs to.

roles | Role[] | The collection of Roles attached to the ApplicationMember.

permissions | Permission[] | The collection of Permissions attached to the ApplicationMember (through the attached Roles).

Example payload:

{
    "id": "XXXXX",
    "application_id": "XXXXX",
    "created_at": "2019-02-12 06:10:30",
    "permissions": [{ ... }],
    "roles": [{ ... }],
    "team": { ... },
    "user": { ... }
}

Team Resource

id | string | The identifier of the Team.

name | string | The name of the Team.

slug | string | The slug of the Team.

applications_count | integer | The number of Applications owned by the Team.

users_count | integer | The number of users that belong to the Team.

Example payload:

{
    "id": "XXXXX",
    "name": "Oh See Media",
    "slug": "oh-see-media",
    "applications_count": 1,
    "users_count": 12
}

User Resource

id | string | The identifier of the User.

name | string | The name of the User.

email | string | The email address of the User.

email_verified_at | string | The date/time the User's email address was verified.

Example payload:

{
    "id": "XXXXX",
    "name": "Owen",
    "email": "owen@remoteauth.com",
    "email_verified_at": "2019-02-12 06:00:30"
}

Permission Resource

id | string | The identifier of the Permission.

name | string | The name of the Permission.

slug | string | The slug of the Permission.

description | string | The description of the Permission.

application_id | string | The identifier of the Application the Role belongs to.

roles | Role[] | The collection of Roles attached to the Permission.

Example payload:

{
    "id": "XXXXX",
    "name": "Permission Name",
    "slug": "permission-name",
    "description": "The description of the Permission goes here.",
    "application_id": "XXXXX",
    "roles": [{ ... }] 
}

Role Resource

id | string | The identifier of the Role.

name | string | The name of the Role.

slug | string | The slug of the Role.

description | string | The description of the Role.

is_default_role | boolean | Indicates if the Role will be added to new ApplicationMembers automatically.

application_members_count | integer | The number of ApplicationMembers that are in this Role.

permissions | Permission[] | The collection of Permissions attached to the Role.

application_id | string | The identifier of the Application the Role belongs to.

Example payload:

{
    "id": "XXXXX",
    "name": "Role Name",
    "slug": "role-name",
    "application_id": "XXXXX",
    "application_members_count": 25,
    "description": "The description of the Role goes here.",
    "is_default_role": false,
    "permissions": [{ ... }] 
}

Endpoints

User endpoints

Get User Profile

This endpoint returns the User's profile.

Endpoint: /api/v1/users/profile

Request method: GET

Response payload: User Resource

List the User's access tokens for a given Application.

Endpoint: /api/v1/users/tokens/application/{applicationId}

Request method: GET

Request path parameters:

  • application_id - Required The identifier of the Application that Access Tokens should be returned for.

Required Scope: manage-access-tokens

Response payload: Array of Access Token Resources

Revoke an Access Token

Endpoint: /api/v1/users//tokens/{accessTokenId}

Request method: DELETE

Request path parameters:

  • token_id - Required The identifier of the Access Token that should be revoked.

Required Scope: manage-access-tokens

Response payload: This endpoint does not send a response payload.

Application Member endpoints

List Application Members between User and Application

This endpoint returns the Application Member records between the authenticated User and the Application. If your application does not support Teams, the array returned will have at most 1 item in it.

If your application does support Teams, this endpoint will return however many assoications the User has to the Application (through various Teams).

Endpoint: /api/v1/users/applicationMembers/byToken

Request method: GET

Response payload: Array of Application Member Resources

List Application Members between User's Teams and Application

This endpoint returns the Application Member records between all Teams the User is a member of and the given Application.

Endpoint: /api/v1/users/applicationMembers/teamMemberships/{applicationId}

Request method: GET

Response payload: Array of Application Member Resources

Create new Application Members

This endpoint creates a new Application Member. This is a simple, but powerful endpoint. It has the ability to create:

  • Application to User (without a Team) member records
  • Application to User (with a Team) member records
  • Application to Team member records

In all cases the application_id is required, however both user_id and team_id are optional although you must specify at least one.

Endpoint: /api/v1/applicationMembers

Request method: POST

Request payload parameters:

  • application_id - Required The identifier of the Application the Application Member should be attached to.
  • user_id - Optional The identifier of the User the Application Member should be attached to.
  • team_id - Optional The identifier of the Team the Application Member should be attached to.

Response payload: Application Member

Teams endpoints

List Teams

This endpoint list the Teams that the currently authenticated User is a member of.

Endpoint: /api/v1/teams

Request method: GET

Response payload: Array of Team Resources

Create Team

This endpoint creates a new Team. After creating the Team, it will then add the authenticated User to the Team with the following permissions:

  • Team Administrator
  • Application Administrator

Endpoint: /api/v1/teams

Request method: POST

Request path parameters:

  • name - The name of the Team.
  • slug - The slug of the Team. A short unique identifier for the Team. Allowed characters are alpha-numeric with hyphens and underscores (-, _).

Response payload: Team Resource

Role endpoints

List the Roles for a given ApplicationMember

This endpoint returns the Role records attached to the given Application Member.

Endpoint: /api/v1/applicationMembers/{applicationMemberId}/roles

Request method: GET

Request path parameters:

  • applicationMemberId - The identifier of the Application Member.

Response payload: Array of Role Resources

Permission endpoints

List the Permissions for a given ApplicationMember

This endpoint returns the Permission records attached to the given Application Member through Roles attached to the Application Member.

Endpoint: /api/v1/applicationMembers/{applicationMemberId}/permissions

Request method: GET

Request path parameters:

  • applicationMemberId - The identifier of the Application Member.

Response payload: Array of Permission Resources

← Glossary →