Administration API
The Administration API is used to provision and manage accounts that will store your customers data as well as manage app connection information. Each account is isolated from one another unless access is granted via sharing settings or setting the datashare
flag when creating the account.
A Postman collection is available to use this API at the bottom of this page
This API is NOT used to access the chart of accounts of a company or any company data like a balance sheet. It is only used to manage accounts to store your customers data. See API for accessing your customers data.
The API methods available include:
Accounts
POST Create Account
POST Listing Accounts
POST Update Account
Connections
GET Health
Embedding
GET Embed Token
Security
POST Create API Key
GET Listing API Keys
POST Update API Key
Authentication
All Admin API endpoints use BASIC AUTH over HTTPS for authentication. An API Key is supplied as the âuserâ while the âpasswordâ can either be an empty string or not set.
All Admin API requests also require in addition to BASIC AUTH an Account-Key
header which contains your unique alphanumeric account key.
Your Account Key can be found within the Admin portal under the Developers
>> Embed
menu.
Accounts
Creating Accounts
You can create a new account via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX" (where XXXX is your account key) that contains a JSON body that looks like:
{
"name": "new client name",
"package_id": "9",
"active": "1",
"email_admin": "newaccountadmin@email.com",
"password": "newadminpassword",
"subdomain": "example",
"type": "standard",
"domain": "www.redirect.com",
"datashare": "1",
"first_name": "Jane",
"last_name": "Doe"
}
Parameter | Definition |
---|---|
| The human readable name of the company you are adding an account for, typically the legal name. This is displayed to the user. |
| Specifies an identifier for a collection of account settings called a `package`. If no |
| A flag that indicates you want this account to be active on creation. Either 0 or 1. |
| Address that indicates the email we should use for communication to the manager of the account, reasons for sending an email might include sending system service/maintenance notices or requests to re-authorize an integration if access has been revoked for some reason. |
| Used to allow the default "admin" account to login with the given password, leave this blank to disable admin login. |
| Required as each new account is accessible under its own subdomain of myintranetapps.com, the text you specify here will be used to create a domain like "my-company.myintranetapps.com". Must be 50 characters or less and use alphanumeric characters and dashes only. If the subdomain is already in use by another account, the request will fail with a 409 response:
CODE
In this case, the request should be retried with a new subdomain. |
| Indicates the account type which is either "reseller" or "standard", for your purposes you should leave this as âstandardâ. |
| An optional field used when you want to add a custom (DNS CNAME) domain name to the system instead of using the myintranetapps.com domain, you shouldn't need this field and can leave blank. If you have not previously setup a DNS CNAME entry for your custom domain do not provide a value in this field or the account creation will not succeed. |
| Indicates that you want the account setup with permissions already active to allow full sharing with the master account. If you want the account to share data with you, be sure to set it to "1"for your use case. |
| Sets the first name of the âadminâ user assigned to the account. Defaults to âAdminâ if not specified in the requestâs body and can be changed later in the Admin portal. |
| Sets the lastt name of the âadminâ user assigned to the account. Defaults to âAdminâ if not specified in the requestâs body and can be changed later in the Admin portal. |
The response you get back will be in JSON and look like:
{
"status_code":200,
"message":"Account successfully created",
"account_key":"<<<UNIQUE_KEY>>>",
"subdomain":"example",
"account_domain":"example.myintranetapps.com",
"name":"new client name",
"admin_email":"newaccountadmin@email.com"
}
You should save the unique key for future reference in your system, you will use this unique account key whenever you need to interact with this account in the future
If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
401 | Missing username/API Key from Basic Auth header | |
401 | Missing 'Account-Key' request header | |
403 | Invalid or expired API Key | If API Key used |
403 | Invalid API Key | If API Key used |
401 | Missing password from Basic Auth header | If username/password used |
403 | Invalid username/account key | If username/password used |
403 | Invalid password | If username/password used |
403 | Operation is not permitted - missing scope: "admin.account.create" | Please check your API Key contains required scope. |
403 | Parent account key must be used when making a 'create account' request. Child account key given. Please check that correct key is used in Account-Key header | |
400 | Missing or empty required fields: {fields list} | Missing one or more required fields: 'type', 'name', 'active', 'subdomain', 'email_admin', 'password' |
403 | Invalid subdomain, must be 50 characters or less and use alphanumeric characters and dashes only | |
409 | Subdomain already in use | |
409 | Custom domain already in use | |
409 | Invalid package_id | |
409 | Invalid environment | |
409 | Account creation failure - accounts | This is internal error during account creation. |
409 | Account creation failure - users | This is internal error during user creation |
409 | Account creation failure - default package | This is internal error during package creation |
Listing Accounts
You can list all accounts previously created via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX" (where XXXX is your account key) that contains a JSON body that looks like:
{
"action": "list_accounts"
}
The response you get back will be in JSON and look like:
{
"status_code":200,
"message": "Accounts list successfully generated",
"accounts":[
{
"name": "General Company Ltd",
"key": "5a70d8fcd44aa9.76285892",
"subdomain": "generalco",
"domain": "",
"package_id": "93",
"email_admin": "cfo@example.com"
}
]
}
If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
401 | Missing username/API Key from Basic Auth header | |
401 | Missing 'Account-Key' request header | |
403 | Invalid or expired API Key | If API Key used |
403 | Invalid API Key | If API Key used |
401 | Missing password from Basic Auth header | If username/password used |
403 | Invalid username/account key | If username/password used |
403 | Invalid password | If username/password used |
403 | Operation is not permitted - missing scope: "admin.account.list" | Please check your API Key contains required scope. |
409 | Account list failure | This is internal error when tried to get list of account |
Updating Accounts
You can update an account previously created via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX" (where XXXX is your account key) that contains a JSON body that looks like:
{
"action": "update_account",
"account_key": "5a70d8fcd44aa9.76285892",
"package_id": "9",
"active": "1",
"email_admin": "newaccountadmin@email.com"
}
Property called "account_key" must be set to the value of the account key of the account to update. Following properties of the JSON posted are optional: "package_id", "active", "email_admin", but there must be at least one property set to perform an update.
The response you get back will be in JSON and look like:
{
"status_code":200,
"message":"Account successfully updated",
"account_key": "5a70d8fcd44aa9.76285892"
}
If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
401 | Missing username/API Key from Basic Auth header | |
401 | Missing 'Account-Key' request header | |
403 | Invalid or expired API Key | If API Key used |
403 | Invalid API Key | If API Key used |
401 | Missing password from Basic Auth header | If username/password used |
403 | Invalid username/account key | If username/password used |
403 | Invalid password | If username/password used |
403 | Operation is not permitted - missing scope: "admin.account.update" | Please check your API Key contains required scope. |
400 | No account_key is set for update | |
400 | No fields to update. Allowed fields: package_id, active, email_admin | |
409 | Account did not updated | This is internal error when during update account |
Connections
Connection Health
To get a list of all app connections and their current status create a GET request (using basic auth) to https://admin.myintranetapps.com/app/api.php?action=connection_health with an "Account-Key" header set to "XXXX" (where XXXX is your account key).
The response you get back will be in JSON and look like:
{
"status_code": 200,
"message": "Connection health generated",
"count": 2,
"connections": [
{
"integration": "quickbooks",
"property": "Sandbox Company_US_1",
"expires": "2021-11-05 19:02:23",
"created": "2019-06-26 22:39:47",
"status": "INACTIVE",
"environment": "sandbox",
"last_sync": "2021-10-12 16:20:38",
"last_sync_error": null,
"last_sync_error_count": null,
"last_sync_error_message": null,
"active": false,
"name": "Dev Startup",
"account_key": "5aa2e93c0ea374.82746293",
"in_error_state": false
},
{
"integration": "quickbooks",
"property": "Boss Widgets Inc",
"expires": "2021-11-05 19:02:23",
"created": "2021-11-05 18:02:23",
"status": "ACTIVE",
"environment": "production",
"last_sync": "2022-05-02 04:05:59",
"last_sync_error": "2022-01-20 04:05:50",
"last_sync_error_count": "0",
"last_sync_error_message": "warning: failed to make request to quickbooks, code:200",
"active": true,
"name": "testborrower",
"account_key": "6170841d16cc84.92698341",
"in_error_state": false
}
]
}
The response contains the following fields:
Field | Definition |
---|---|
integration | The unique identifying key for a particular app |
property | Some apps manage access to multiple properties/accounts via a given set of credentials. For many apps this field will be blank but for those that support accessing different properties the name of the property will be the value of this field. |
expires | The date and time the current access token expires. Access tokens are refreshed automatically |
created | The date and time this app connection was created in UTC |
status | The current status of the app connection. One of: |
environment | The app connection environment, typically this is either âproductionâ or âsandboxâ depending on the account settings |
last_sync | The date and time of the last full synchronization for this app in UTC |
last_sync_error | The date and time of the last full synchronization that resulted in an error in UTC |
last_sync_error_count | The number of sequential errors that have occurred when performing full synchronization, this counter resets to 0 when a successful synchronization occurs. Automatic synchronization will pause when 10 attempts at synchronization fail. |
last_sync_error_message | The technical error message indicating the reason for an error |
active | Whether or not this app connection is an active connection (true) or has been disconnected (false). Deprecated - use âstatus' instead |
name | The name of the account associated with the connection |
account_key | The account key associated with the connection |
in_error_state | Whether or not the connection is currently considered in error, 0 or 1 |
integration_platform | The platform an app is categorized into (accounting, commerce, banking, billing) |
If something goes wrong while processing your GET request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
401 | Missing username/API Key from Basic Auth header | |
401 | Missing 'Account-Key' request header | |
403 | Invalid or expired API Key | If API Key used |
403 | Invalid API Key | If API Key used |
401 | Missing password from Basic Auth header | If username/password used |
403 | Invalid username/account key | If username/password used |
403 | Invalid password | If username/password used |
403 | Operation is not permitted - missing scope: "admin.connection.health" | Please check your API Key contains required scope. |
400 | Invalid status {status} received in 'statuses' param. Valid values are INACTIVE,ACTIVE,PENDING | |
405 | HTTP request method not allowed | Action (parameter âactionâ, for example âconnection_healthâ) is not supported |
Fetching connection information for a specific account
Adding an additional GET parameter named account_key
will limit the result set to only contain connections for the given account, e.g. https://admin.myintranetapps.com/app/api.php?action=connection_health&account_key=5aa2e93c0ea374.82746293
Filtering connections based on status
Adding an additional GET parameter named statuses
will filter the result set based on status. The statuses
parameter should be a comma-separated list of statuses you want to include in the response. For example, https://admin.myintranetapps.com/app/api.php?action=connection_health&statuses=ACTIVE would only return ACTIVE connections in the response.
https://admin.myintranetapps.com/app/api.php?action=connection_health&statuses=PENDING,INACTIVE would only return PENDING and INACTIVE connections in the response.
Valid values that can be included in the comma-separated list are ACTIVE, PENDING, or INACTIVE.
Filtering connections based on platforms
Adding an additional GET parameter named platforms
will filter the result set based on the platform the connections are categorized to. The platforms
parameter should be a comma-separated list of platforms you want to include in the response. For example, https://admin.myintranetapps.com/app/api.php?action=connection_health&platforms=accounting would only return connections from the accounting platform in the response.
https://admin.myintranetapps.com/app/api.php?action=connection_health&platforms=accounting,commerce would only return connections from the accounting and commerce platforms in the response.
Valid values that can be included in the comma-separated list are accounting, commerce, billing and banking.
Embedding
Embed Token
In order to use the Link Page Element widget you will need an embed token.
You can create a new embed token via a GET request (using basic auth or API key) to https://admin.myintranetapps.com/app/api.php?action=embed_token with an "Account-Key" header set to "XXXX" (where XXXX is your account key)
There are three ways to use Embed Tokens:
To access your own account. In this case, do not use the
account_key
orobserve_account
params.To access a customer account. In this case,
account_key
should be the account key of the customer account you are trying to access. Do not use theobserve_account
param.To access your own account and view a customerâs pages. In this case,
account_key
should be the account key of the customer whose pages you are trying to view.observe_account
should be set to1
.
The Account-Key header is different from the account_key query parameter, the former is used to authenticate to the API, the latter is used to specify which account you need a token for
Parameter | Definition |
---|---|
| Should be set to âembed_tokenâ |
| If If |
| If set to 1, you will access your own account with the ability to view another accountâs pages. |
The response you get back will be in JSON and look like:
{
"status_code": 200,
"message": "Embed token generated",
"token": "et-629cb2c4-a972-47b5-8ed0-f4977a8a8010",
"expires": "2022-09-08T23:48:59+00:00",
"params": {
"account_key": "5f66c0b15206d1.36412804",
"observe_account": true,
"redirect_url": false,
"account_domain": "bank.myintranet.app"
}
}
You will need to pass the token
and account_domain
properties as parameters when instantiating the Link Page Element widget
If something goes wrong while processing your GET request ("status_code" value will differ from 200), the "message" property will contain an error description.
Security
Add API Key
You can create a new API Key via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX" (where XXXX is your account key) that contains a JSON body that looks like:
{
"action": "add_key",
"name":"a test key",
"scope":["admin.account.create","admin.account.update"],
"active": "1"
}
Parameter | Definition |
---|---|
| Must be set to âadd_keyâ |
| The human readable name of the API Key you are adding. This is only used to help you differentiate keys |
| Specifies an array of the features and/or data this API key will be able to access |
| A flag that indicates you want this API Key to be active on creation. Either 0 or 1. |
The response you get back will be in JSON and look like:
{
"status_code": 200,
"message": "New API Key Added Successfully",
"key": "sk_vtL5a3SXOSi89QR.IIsj7OTWOlYt6RPxTmeTdRqViHWi4B8h"
}
You should save the key for future reference in your system, you will use this unique key whenever you need to interact with this account in the future
If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
401 | missing name or scope |
Listing API Keys
To get a list of all API Keys create a GET request (using basic auth) to https://admin.myintranetapps.com/app/api.php?action=listing_keys with an "Account-Key" header set to "XXXX" (where XXXX is your account key).
The response you get back will be in JSON and look like:
{
"status_code": 200,
"message": "API Key Listing",
"count": 2,
"keys": [
{
"name": "Test Key 1",
"key": "sk_Stezb",
"id": 134,
"active": 0,
"created": "2022-07-27 20:53:37",
"modified": "2022-07-27 21:09:49",
"api_scope": [
"account.create",
"integration.connect"
]
},
{
"name": "Test Key 2",
"key": "sk_96wAU",
"id": 135,
"active": 1,
"created": "2022-07-27 21:10:05",
"modified": "2022-11-15 04:19:16",
"api_scope": [
"api.read",
"api.write",
"integration.connect"
]
}
]
}
The response contains the following fields within the keys field:
Field | Definition |
---|---|
name | A human friendly reference name used to help distinguish different keys |
key | The first few characters of the API key. Note it is not possible to retrieve the entire API key for security purposes. |
id | The unique system identifier of this API Key |
active | A value of 1 indicates this key can be used, a value of 0 indicates the key is inactive. |
created | The date and time this app connection was created in UTC |
modified | The date and time this app connection was last modified in UTC |
api_scope | An array of scopes this API key has authorization for, i.e. the actions this API key is entitled to do. |
If something goes wrong while processing your GET request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
405 | HTTP request method not allowed | Action (parameter âactionâ, for example âlisting_keysâ) is not supported |
Update API Key
You can update an API Key via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX" (where XXXX is your account key) that contains a JSON body that looks like:
{
"action": "update_key",
"id": 136,
"name":"a new key name",
"scope":["admin.account.create","admin.account.update"],
"active": 1
}
Parameter | Definition |
---|---|
| Must be set to âupdate_keyâ |
| The ID of the API Key you want to update |
| The human readable name of the API Key you are updating. This is only used to help you differentiate keys |
| Specifies an array of the features and/or data this API key will be able to access |
| A flag that indicates you want this API Key to be active. Either 0 or 1. |
The response you get back will be in JSON and look like:
{
"status_code": 200,
"message": "API Key Updated Successfully",
"id": 136
}
If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.
Error responses
HTTP response status | Error message | Description |
---|---|---|
400 | Bad Request | Check that you are sending a standard âHostâ header in your request |
401 | missing id, name or scope |
Multi-level Accounts
Multi level accounts can be used by service vendors to provide a branded experience to the financial services firms they work with and in turn their business customers.
To enable multi-level accounts you will need to make a request to our support help desk
Account levels:
Some things are done differently with multi-level accounts and are noted here:
When creating an account the
type
parameter should be set to a value ofreseller
After creating an account for your customer you should create and store an API key for their account and use this to conduct actions on their account or their SMB customers.
Accounts are managed in a parent-child relationship, generally child accounts will inherit configuration from their parent account
Postman Collection
A Postman collection is provided to help you start developing with our API quickly.
When sending requests via Postman, ensure you send standard HTTP headers such as Host, Content-Type, Accept and so on.

When sending requests via Postman, ensure you send standard HTTP headers
Administration.postman_collection.json
Collection environment variables:
Variable | Value | Description |
---|---|---|
| admin | Unless you have a custom domain this should be set to |
| myintranetapps.com myintranetapps.ca bossinsights.uk | Either |
| <YOUR ACCOUNT KEY> | The unique alphanumeric key assigned to your account. This will be sent in the header of each API request. e.g. |
| <YOUR API KEY> | An API key from your account OR alternately a user that is part of the admins group |
| empty string | When using an API Key this should be an empty string. ONLY when using an admin user this should be the password of that user |
Your Account Key can be found within the Admin portal under the Developers
>> Embed
menu.