Auth API

Use the Auth API to create, delete, and list OAuth2 apps, create, update, and get a user Oath2 token, and set and get SAML mappings.

For the Auth API, api-root defines where to route API requests for your Instabase instance:

import json, requests

api_root = "https://www.instabase.com/api/v1/auth"

See Instabase API authorization and response conventions for authorization and error convention details.

Create OAuth2 app

This API creates an OAuth2 app and token for a user by specifying their username in the request route.

This API is callable only by Site Admins.

Request

The request must be:

headers = {"Authorization": "Bearer {0}".format(token)}
data = json.dumps(
    {
        "redirect_uri": "redirect.com",
        "description": "My test app",
        "app_name": "ib_testapp",
        "create_token": True
    }
 )
resp = requests.post(api_root + "/oauth/owner/<username>/app", headers=headers, data=data).json()

Fields:

  • redirect_uri (required) - A redirect URL

  • description (required) - A description of the app

  • app_name (required) - The name of the OAuth2 App. Only alphanumeric characters and underscores are allowed. The app name must be unique across the entire Instabase instance

  • create_token (optional) - Create an access token.

    • true - The token is created and returned in the response

    • false - A token is not created. Instead, you can use the Create OAuth2 Token API

Response

If successful, the response contains information about the app that was created. If create_token was set to True in the request, the response contains the token information.

{
   "status":"OK",
   "app":{
      "owner":"<username>",
      "app_name":"ib_testapp",
      "app_id":"<app-id>",
      "app_secret":"<app-secret>",
      "description":"My test app",
      "redirect_uris":[
         "redirect.com"
      ]
   },
   "token":{
      "app_id":"<app-id>",
      "token_type":"Bearer",
      "access_token":"<access-token>"
   }
}

Get a list of all OAuth2 Apps for a user

This API is callable only by Site Admins.

To get the list of OAuth2 Apps for a user, specify the username of the user in the request route.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "/oauth/owner/<username>/app", headers=headers).json()

Response

{
   "status":"OK",
   "apps":[
      {
         "owner":"user1",
         "app_name":"test_app",
         "app_id":"<app-id1>",
         "app_secret":"<app-secret1>",
         "description":"Testing app",
         "redirect_uris":["url.uk,url.ca"]
      },
      {
         "owner":"user1",
         "app_name":"dev_app",
         "app_id":"<app-id2>",
         "app_secret":"<app-secret2>",
         "description":"Developer app",
         "redirect_uris":["dev.uk,dev.ca"]
      }
   ]
}

Delete All OAuth2 Apps and Tokens

This API is callable only by Site Admins.

This API deletes all OAuth2 Apps and Tokens associated with a user to prevent the user from making API requests.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.delete(api_root + "/oauth/owner/<username>/app", headers=headers).json()

where is the user whose OAuth2 Apps/Tokens you want to revoke.

Response

{
  "status": "OK"
}

Get a User’s OAuth2 App

This API is callable only by Site Admins.

This API gets information about a user’s OAuth2 App by specifying the username in the request route.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "/oauth/owner/<username>/app/<app_name>", headers=headers).json()

Response

{
   "status":"OK",
   "app":{
      "owner":"heymian",
      "app_name":"test_app",
      "app_id":"<app-id>",
      "app_secret":"<app-secret>",
      "description":"Testing app",
      "redirect_uris":["url.uk,url.ca"]
   }
}

Create/Update OAuth2 Token

This API creates and updates an OAuth2 Token for a user’s OAuth2 App by specifying the username and the app_name in the request route.

This API is callable only by Site Admins.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
data = json.dumps(
    {
       "token": "abcdefghijklmnopqrs",
        "token_duration_sec": 60
    }
)
resp = requests.post(api_root + "/oauth/owner/<username>/app/<app_name>/token", headers=headers).json()

Fields:

  • token (optional) - The token string. If not specified, a random token is generated. The token must be composed of alphanumeric characters with a minimum length of 16 characters.

  • token_duration_sec (optional) - The number of seconds before the authentication token expires. Tokens without this parameter expire in 50 years.

Response

{
   "status":"OK",
   "token":{
      "app_id":"<app_id-id>",
      "token_type":"Bearer",
      "access_token":"<access-token>"
   }
}

Get OAuth2 Token

This API gets the OAuth2 token associated with a user’s OAuth2 App by specifying the username and the app_name in the request route.

This API is callable only by Site Admins.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "/oauth/owner/<username>/app/<app_name>/token", headers=headers).json()

Response

{
   "status":"OK",
   "token":{
      "app_id":"<app_id>",
      "token_type":"Bearer",
      "access_token":"<access-token>"
   }
}

Get SAML Mappings

This request returns a list of all SAML mappings. Users that belong to the SAML group denoted by external name are automatically added to the corresponding Instabase Group.

This API can be invoked only by a site admin.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "/saml/mappings", headers=headers).json()

Response

If successful:

{
  "status": "OK",
  "mappings": [
    {
      "external_name": "engineering",
      "group_name": "tech"
    },
    {
      "external_name": "sales",
      "group_name": "business"
    }
  ]
}

Set SAML Mappings

This API sets SAML mappings. To clear previous mappings, set the mappings field to an empty list.

This API can be invoked only by a site admin.

Note

This request overrides, but does not add to, previously set mappings.

Request

The request must be:

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
args = {
  "mappings": [
    {
      "external_name": "developers",
      "group_name": "engineering"
    },
    {
      "external_name": "tools",
      "group_name": "infrastructure"
    }
  ]
}
data = json.dumps(args)
resp = requests.post(api_root + "/saml/mappings", headers=headers, data=data).json()

Response

If successful:

{
  "status": "OK"
}