# Introduction The Medable platform is designed to serve a diverse group of professionals working in healthcare, from researchers to software engineers. If you aren't certain which product is right for you, please take some time to explore our product offerings below. ## Cortex Cortex provides tools you need to build and scale secure, compliant health apps. Cortex is designed to be used by software developers in healthcare to build engaging patient experiences without the need to write a single line of back-end code. Cortex is a full-stack solution for developing your mobile and web applications, including secure data storage, user management, notifications, custom logic, and advanced analytics. Cortex offers myriad features that you can leverage to simplify development. We are excited to see what kind of apps you will build on our Cortex platform. ## What's Next? For an overview of what Cortex can do, review Cortex's features. {% content-ref url="/pages/-Mj66MZ9Lzax6ZeeUaIb" %} [Features](/cortex-features) {% endcontent-ref %} Start with Organizations in the Cortex Guide if you want to start working with Cortex immediately. {% content-ref url="/pages/-Mj66MZOwGS9BnjR4MEh" %} [Organizations](/getting-started/cortex-user-guide/organizations) {% endcontent-ref %} To learn more about Cortex's architecture, start with an overview of Cortex API. {% content-ref url="/pages/-Mj66MZvSKofX9mazbcM" %} [Overview](/cortex-api/cortex-api) {% endcontent-ref %} # Features | Feature Sets | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Account Provisioning | Medable provides a number of standard objects, such as the Account object, which is critical to user management. When you sign up and your orgs are provisioned, an instance of the Account object is created for your initial admin user, which is what allows you to log into your org or orgs. | | Configure Custom Data Models | Medable is designed to be extensible and customizable, so extending the standard objects and creating your own objects to suit your needs is quick and easy. You can extend the API by creating new custom objects and extending the standard objects with custom properties. You can do this via the API if you have the Administrator or Developer roles, or via the Admin UI. You can create relationships between objects such as one-to-many and many-to-many. | | Roles and Permissions | Access control lists (ACLs) allow you to define fine-grained access to object instances and their properties directly in your data model. | | Authentication Methods | | | Developer Tools | Cortex developer tools allow you to export org configurations from one org and import them to another. These tools also allow you to create a git-mergeable format for org configuration. As such, the exports are minimalistic in nature, having only the properties required to rebuild during import. The developer tools consist of Cortex routes, an npm module (which includes a command interface), and a reference implementation Atom plugin that utilizes the npm module. You can find documentation for installation and usage at the following link: . | | Expressions | Expressions allow developers to execute conditional logic when running scripts or policies. These operators are available to construct logic for use in the aggregation pipeline stages. | | Audit Logs and Dashboards | Some event logs, such as tracking invalid login attempts, are explicitly required by 21 CFR 11 regulations. Events that affect or are required to document compliance of 21 CFR 11, Good Clinical Practice (GCP), and other regulatory requirements are logged and visible in human-readable format in the Admin Portal. | | Service Accounts | For org and study configuration to be moved between environments, the system should be able to easily map user accounts; however, this process is difficult because of passwords and unique email addresses. Roles are currently mapped but user accounts are not. Because views and scripts can be run as a user and resources created must have a creator, packages need user accounts to act on their behalf. Service accounts enable running a view or script without using a named account. Developer tools and deployments can import and export service accounts. | | Notifications | | | Script Transforms |

Though aggregation and projection is often much faster and less expensive that running a script transform, sometimes complex computation or data-interleaving is required that would be impractical to accomplish within a single script instance.‌

Transforms work by applying a script to an output cursor. Depending on the complexity and number of documents, a cursor transformation may be executed and re-queued multiple times before the cursor is finally exhausted.

| | Televisit | Cortex supports on platform secure video communication through Twilio Video. | | Querying | Objects can be queried using the available query arguments, allowing developers to easily search large amounts using the API. | | Aggregating | Aggregation operators can be used to create expressions in the aggregation pipeline. | | Scripting |

The Medable platform offers a JavaScript API for developers to create, read, update, and delete cortex objects; query and aggregate data; send custom notifications; perform callouts; console and debug logging; create object triggers; run scheduled jobs; create custom api routes and more.

All scripts run synchronously. There are no callbacks or timers and as such no implementation of functions such as setInterval, setTimeout or setImmediate.

| | PDF Generation | Renderer runs as a service, and will allow to convert HTML/CSS templates into PDF/CSV/HTML files, and put them into different kind of targets (FileObject, SFTP, or return as base64 result). | | Localization | Cortex supports localization through custom localized string properties. Localization for a string property can be enabled via string property options. Once enabled, you can write to and read from that property in any specified locale. | | sFTP Module | The SFTP module allows you to transfer files over an encrypted ssh transport between a Cortex script and a remote destination | # Cortex User Guide # Organizations ## What is an organization? In Cortex, your organization (org) is your private Cortex environment. Only you and those you allow have access to this environment and the data within it. ## Organization environments ### Production The Medable production environment has active end-users and is for storing critical and/or sensitive data. Production environments are accessed from the following endpoints: * **Admin UI:** `https://app.medable.com` * **API:** `https://api.medable.com` ### Development The Medable development environment is used for active app development and testing without impacting production environments. It's your own container to configure to your liking. Later as you progress from deployment to production, you might even request a staging or production environment to fit your development cycle. Development environments are accessed from the following endpoints: * **Admin UI:** `https://app.dev.medable.com` * **API:** `https://api.dev.medable.com` {% hint style="info" %} **Note:** Critical or sensitive data should not be stored in development environments, as these environments do not employ all of the necessary protection safeguards. {% endhint %} ### QA QA environments are accessed from the following endpoints: * **Admin UI:** `https://app.qa.medable.com` * **API:** `https://api.qa.medable.com` # Log in ## Log in to your Medable admin portal Complete the following steps to log in to the Medable control panel for your org: 1. Navigate to the development or production environment using one of the following URLs. Replace `` with the org code that was specified when signing up: * **Development:** `https://app.dev.medable.com/` * **Production:** `https://app.medable.com/` 2. Enter your username (the email address you specified when signing up) on the login screen. 3. Enter your password. 4. Click **Sign In**. # Generate an API key ## Create a new app to generate an API key By now you've created an org and have successfully logged in as an administrator. Before you can begin making API requests, you will need to first generate an API key. {% hint style="info" %} **Note:** For our examples in this guide, we are completing each step in a development environment. {% endhint %} To generate an API key, complete the following steps after logging in to your org: 1. Select **Settings** > **Apps** on the left-hand menu. 2. Click **New App**. The Create App screen is displayed. 3. Enter a name for the new app in the Label field. 4. (Optional) Check **Sessions** to create a session-based app. 5. (Optional) Uncheck **CSRF Protection**. If this is checked, you will need to send the `medable-csrf-token` header with each authenticated request. 6. Click **Create App**. The API key appears in the API Key column. {% hint style="info" %} **Tip:** CSRF protection is not necessary for this example, but we highly recommend enabling it for production web apps. {% endhint %} In our example, we created a new app called NewHealth App with the API key `mwidxhb8ShcqmV1B9iOYJh`. ![Create App](/files/-Mj66TtRCmLZavo5tpyF) # Make your first API request ## Medable API requests To make your first Medable API request, you need to know four things: 1. **The API endpoint:** for example, `api..medable.com/` 2. **The API key:** for example, `mwidxhb8ShcqmV1B9iOYJh` 3. **Authentication credentials:** an email and password 4. **The API client:** a terminal, web, iOS, or Android ## The API endpoint The endpoint for your API requests will look like the following: {% tabs %} {% tab title="HTTP" %} ```bash https://api.dev.medable.com/{{your_org_code}}/v2/{{api_resource}} ``` {% endtab %} {% endtabs %} Where `your_org_code` is the org code you specified when signing up and `api_resource` is the resource you are trying to access, such as an account. And remember, since we're making this request to the development org, we use the api.**dev**.medable.com URL. In our case, we'll use the example org code we used when we made the new app: `newhealthco`. {% hint style="info" %} **Note:** When making requests, use the plural name for `api_resource`. For example, if the resource is `account`, use `accounts` in your endpoint: `https://api.dev.medable.com/newhealthco/v2/accounts` {% endhint %} ## The API key Copy the API key that you generated in the previous step (see [Generate an API key](/getting-started/cortex-user-guide/gen-api-key)). In our example, the API key is `mwidxhb8ShcqmV1B9iOYJh`. ## Authentication credentials Because we specified that our app uses sessions, a username and password is needed to authenticate and initiate a user session. For the username, use your email address. In our case, it's `john@newhealthco.com`. For the password, use the password you set when signing up. If you're interested in signature-based authentication, see [Authentication](/getting-started/cortex-user-guide/authentication#signature-based-authentication). ## The API client There are a number of tools out there that make it easy to make API requests. One option is Postman and another option is the live API explorer in the API Reference page. In this guide, we'll keep it simple and make our requests from the command line using [curl](https://curl.se/). ### Make a request {% hint style="warning" %} **Note:** This section is written assuming the request is being made through an OSX terminal. {% endhint %} Now that you're ready to make a request, you simply have to issue the command in the form of `curl \[options...\] URL`. Let's give it a shot using the API endpoint: {% tabs %} {% tab title="Request" %} ```bash $ curl https://api.dev.medable.com/newhealthco/v2/accounts ``` {% endtab %} {% tab title="Response" %} ```javascript { "object":"fault", "name":"error", "code":"kNotFound", "status":404, "reason":"Invalid application client api key.", "message":"Resource not found" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Tip:** Add `| python -m json.tool`to the end of the curl request to pretty-print the JSON response. {% endhint %} We got a result back! Unfortunately, the result is a fault. This is because we need to pass in a few more options to get the request to work. First, we need to add the API key header. We can do this using the following option: `-H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh"` So let's give that a try: {% tabs %} {% tab title="Request" %} ```bash $ curl -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" https://api.dev.medable.com/newhealthco/v2/accounts ``` {% endtab %} {% tab title="Response" %} ```javascript { "object":"list", "data":[ ], "hasMore":false } ``` {% endtab %} {% endtabs %} The fault is gone, but now we get back an unexpected result. Rather than a list of accounts, which should at least have our own account in it, we get an empty result. This is because the Account resource requires authentication to access. If we had tried to access a specific account using an account ID (`575f58281d0c03a53ccc3ac6` in this case), we would receive a `403` error like so: {% tabs %} {% tab title="Request" %} ```bash $ curl -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" https://api.dev.medable.com/newhealthco/v2/accounts/575f58281d0c03a53ccc3ac6 ``` {% endtab %} {% tab title="Response" %} ```javascript { "object":"fault", "name":"error", "code":"kAccessDenied", "status":403, "reason":"Read access denied.", "message":"Access to this resource is denied" } ``` {% endtab %} {% endtabs %} So let's authenticate. To log in, we need to `POST` to the login route with our username and password. For more information on the Account resource and the available routes, see the [API documentation on Accounts](https://medable.gitbook.io/cortex/-LlEM5zIUXLGk89rMHaQ/v/master/cortex-api/objects/account). One more thing before we log in. For session-based apps, Medable uses cookies to track the session ID. So we need to enable cookie support in curl. To do this, we pass in the additional options:`-b cookies.txt -c cookies.txt` The first option `-b` reads any existing cookies from cookies.txt and sends with the request. The second option `-c` writes any cookies coming from Medable to cookies.txt. {% tabs %} {% tab title="Request" %} ```bash $ curl -b cookies.txt -c cookies.txt -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" -d "email=john@newhealthco.com&password=This is not the password\!" https://api.dev.medable.com/newhealthco/v2/accounts/login ``` {% endtab %} {% tab title="Response" %} ```javascript { "_id":"575f58281d0c03a53ccc3ac6", "object":"account", "created":"2016-06-14T01:04:40.888Z", "updated":"2016-06-14T01:08:06.647Z", "updater":{ "_id":"575f58281d0c03a53ccc3ac6", "object":"account", "path":"/accounts/575f58281d0c03a53ccc3ac6" }, "access":6, "favorite":false, "email":"john@newhealthco.com", "name":{ "first":"John", "last":"Smith" }, "mobile":"+15555555555", "locale":"en_US", "state":"verified", "locked":false, "key":{ "fingerprint":"73ad85a0-31cc-11e6-ba07-3f24c7443557", "secret":"PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp" }, "roles":[ "000000000000000000000004", "000000000000000000000007", "000000000000000000000006" ], "shared":false } ``` {% endtab %} {% endtabs %} And we've successfully logged in! We know this because after a successful login, we receive our account object in the response. If, instead of a response similar to the above, you receive a fault response that resembles this: ```javascript { "object": "fault", "name": "location", "code": "kNewLocation", "status": 403, "message": "A new location has been added to the account." } ``` This means that two-factor authentication (2FA) has been initiated. Note that the fault could be `kNewLocation`, `kUnverifiedLocation`, or `kLocationClientMismatch`. When this happens, you will receive a verification token via SMS to your mobile number. Once you receive that token, you'll need to authenticate again as well as send along `verificationToken` like so: ```bash curl -b cookies.txt -c cookies.txt -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" -d 'email=john@newhealthco.com&password=NotYourPassword&location[verificationToken]=123456' https://api.medable.com/newhealthco/v2/accounts/login ``` For more information on 2FA, see [Two-factor authentication](/getting-started/cortex-user-guide/two-factor-auth). Now that we've logged in and have an active session, let's try that account request again. {% tabs %} {% tab title="Request" %} ```bash $ curl -b cookies.txt -c cookies.txt -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" -d "email=john@newhealthco.com&password=This is not the password\!" https://api.dev.medable.com/newhealthco/v2/accounts/login ``` {% endtab %} {% tab title="Response" %} ```javascript { "_id":"575f58281d0c03a53ccc3ac6", "object":"account", "created":"2016-06-14T01:04:40.888Z", "updated":"2016-06-14T01:08:06.647Z", "updater":{ "_id":"575f58281d0c03a53ccc3ac6", "object":"account", "path":"/accounts/575f58281d0c03a53ccc3ac6" }, "access":6, "favorite":false, "email":"john@newhealthco.com", "name":{ "first":"John", "last":"Smith" }, "mobile":"+15555555555", "locale":"en_US", "state":"verified", "locked":false, "key":{ "fingerprint":"73ad85a0-31cc-11e6-ba07-3f24c7443557", "secret":"PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp" }, "roles":[ "000000000000000000000004", "000000000000000000000007", "000000000000000000000006" ], "shared":false } ``` {% endtab %} {% endtabs %} Success! You've made your first API request! # Configure the org settings ## Adjust your organization settings One of the first things you'll want to do in your org is adjust the organization settings. These are settings that apply across your entire org, for all applications, users, etc. To adjust the Organization Settings, select **Settings** > **Organization** on the Cortex menu. ![Organization Options](/files/-Mj66OaFM8BWUqvSpQiF) The Organization Options screen displays three tabs: Options, Appearance, and Maintenance Mode. ### Options The available options under the Options tab are: * **Organization Name:** Enter the human-readable name of your org that can be used in templates. Typically this will be your company/organization name. * **Enable Registration:** Enable this to turn on the registration route (see Register an Account in the API documentation for more details). You would want to enable this if you intend to allow users to self-register in your apps. * **Enable Provider Registration:** Enable this to allow users to register with the Provider role. * **Manual Provider Verification:** Enable this to require provider accounts to be verified by an org administrator before they can collaborate with other users. * **Invitations Required:** Enable this to require users to provide an invitation token when registering. This is useful for invite-only, controlled releases of apps. * **Activation Required:** Enable this to require registered users to be manually activated before they can sign in. This is useful for the controlled release of apps. * **Minimum Password Score:** Select the required password strength for org users. Medable uses the `zxcvbn` password strength estimator to evaluate password strength. * **Simultaneous Logins:** Enable this to allow a user to have multiple simultaneous sessions. When not checked, only a single session-based login is allowed at a time for a user. * **Login Verification Bypass:** Enter a comma-delimited list of email addresses that can skip two-factor authentication. For more information, see [Two-factor authentication](/getting-started/cortex-user-guide/two-factor-auth). * **Unauthorized Attempts Account Lock:** Enter the number of failed authentication attempts allowed for a user before the account is locked. Enter 0 to disable locking. * **Account Lock Duration:** Enter the number of minutes an account will be locked out after failing authentication. Enter 0 to lock indefinitely. ### Appearance Under the Appearance tab, you can upload a custom logo and a favicon to your Medable org's control pane. ![Organization Appearance](/files/-Mj66OaHE064LXn2uH2o) ### Maintenance Mode Under the Maintenance Mode tab, you can administratively place your org into maintenance mode. This can be useful when you need to temporarily prevent users from logging in to your apps while you are making updates. ![Organization Maintainance](/files/-Mj66OaIJrxgQDY6_NRW) # Set up a data model ## Introduction Medable provides a number of standard objects such as the Account object, which is critical to user management. When you sign up and your orgs are provisioned, an instance of the Account object is created for your initial admin user, enabling you to log in to your org(s). Medable is designed to be extensible and customizable, so extending the standard objects and creating your own objects to suit your needs is quick and easy. When extending a standard object or creating your own objects and properties, the resulting objects are considered "custom" objects and properties. To avoid any naming collisions between standard and custom objects and properties, any customizations are prefixed with `c_`. So, for example, if you were to add a custom "address" document property to the Account object, the property would appear in the API as `c_address`. The same holds true for object names. If you were to create a custom "Prescription" object, the API name for the object would be `c_prescription`. This only impacts code and does not impact the UI for your applications. Although an object or property may have a `c_` prefix, it can still have a human-readable label. # Create custom objects ## Create a custom object To create a custom Medable object: 1. Log in to the admin portal. 2. Select **Settings** > **Objects** to access the Objects screen. 3. Click **New Custom Object** on the Custom Objects pane. 4. On the Create Object screen, you can fill out: * **Object Label:** Enter the label for your object that will be displayed in the UI. * **Object Name:** Enter the API name for your object. * **Connection Settings:** See [Connections](/getting-started/cortex-user-guide/connections) for more details. * **Allow Connections:** Specify whether connections can be created for this object. * **Require Connection Accept:** Specify whether connections to this object require acceptance. * **Send Connection Notifications:** Specify whether to send notifications to targets when connections to this object are created. * **Access Control Settings:** See [Access Control](/cortex-api/objects-definition#access-control) in the API documentation for more details. * **Creatable By:** Select users or roles that can create instances of this object. * **Object Access:** Select the access levels that users and roles have to instances of this object. 5. Click **Create Object**. Your object will be created, and its details will be displayed. ![Create Object](/files/-Mj66RJAZi0klvTpCJjK) ### Create a Prescription object Here, we'll create a Prescription object. We'll set the object label to "Prescription" and the name to "prescription." Note that all custom objects and property names are automatically prefixed with `c_` to help prevent collisions with standard objects and properties. So although we provide the name `prescription`, it will become `c_prescription` after saving. ![Create Prescription Object](/files/-Mj66RJBZln9kPw0LpiS) ![Prescription Definition Object](/files/-Mj66RJCVhftsFhRrps-) ### The object's plural name Now the Prescription object has been created. All of the details were provided while creating the object except for one detail: Plural Name. The plural name is generated automatically. Use the plural name when referencing your object via the API (for example, `GET /c_prescriptions`). Now you're ready to add properties to the custom object. # Add custom properties ## Create custom properties Custom properties can be added to standard objects (such as the Account object) and to custom objects like the Prescription object. You can add a custom property from an object's detail view: 1. Select **Settings** > **Objects** on the left-hand menu. 2. Select the label of an object you'd like to view. 3. Scroll down to the Custom Properties pane and click **New Property**. 4. On the Create Property screen, you can fill out: * **Property Label:** Enter the label for your property that will be displayed in the UI. * **Property Name:** Enter the API name for your property. * **Property Type:** Select the type of property to create. For more information on property types, see primitive types in the API documentation. * **Property Access:** Select the access levels that users and roles have to this property. 5. Click **Create Property**. The Create Property screen is displayed. ![Create Patient Property](/files/-Mj66O6DsfHlhGXQ-6aJ) Since we're creating a Prescription object, we'll need to create a number of properties to represent a patient's prescription. The following table shows a few properties that we'll need to create: | Label | Name | Type | Description | | -------- | ------------ | --------- | --------------------------------- | | Date | `c_date` | Date | Date of the prescription | | Dispense | `c_dispense` | Number | Amount to dispense per refill | | Patient | `c_patient` | Reference | Reference to the patient account | | Provider | `c_provider` | Reference | Reference to the provider account | | Refills | `c_refills` | Number | Number of refills | | Rx | `c_rx` | String | Prescription details | ### Create a Patient property First, we'll create the Patient property. 1. On the Create Property screen, select **Reference** from the Property Type list. More options particular to the reference property type will be displayed. 2. For Source Object, select **Account**. We want to relate the prescription to the patient's account record. 3. For Required Access, select **Connected**. This means that whoever is creating the prescription will need to have at least that level of access to the patient's account record. 4. For Expandable, leave it as selected. 5. For Grant Access, select **Read**. 6. Check **Indexed**. This will allow us to query prescriptions by `patient account \_id`. 7. Click **Create Property** once the property has been configured. After creating the Patient property, you will see it listed under Custom Properties of the object's detail view. ![Reference Property](/files/-Mj66O6EsHvfyyF5OWdJ) ### Create a Date property Next, we'll create the Date property. 1. On the Create Property screen, select **Date** as the property type. 2. Check **Date Only**, as this does not need to be a date-time property. 3. Check **Indexed** so that we can query prescriptions by date. 4. Click **Create Property** once the date property has been configured. ![](/files/-Mj66O6Fs-A7z9nHxpaJ) ### Create an Rx property Next, we'll create the Rx property. This time we will: 1. On the Create Property screen, select **String** as the property type. 2. Check **Indexed**. 3. Enter a value in the Max Length field that is appropriate. 4. Click **Create Property** once the property has been configured. ![](/files/-Mj66O6GO_1S6ysttrjd) ### Create additional properties Finally, create a few more properties to complete the object. ![](/files/-Mj66O6HHHVE1XLJLqNm) # One-to-many relationships ## Introduction As we've seen already when creating a custom object, you can relate one object to another with a `Reference` property type. That creates just one side (the many) of the one-to-many relationship, however. From the parent object, how do we get the list of the many child objects from the relationship? In this how-to, we'll walk through modeling that out completely by adding a `List` property. ### Setup To get a one-to-many relationship setup you just need: 1. A parent object (In this case we'll use `Account` for the patient). 2. A child object (in this case we've already created the `Prescription` object). 3. A Reference or ObjectId property on the Prescription object with its Source Object set to Account and indexed set to true 4. A List property on the Account object that provides the list of related Prescriptions when getting the Account. Now, the Account object is already there, so there's nothing to do with it just yet. Let's start with the child object, in this case the "Prescription" object. If you haven't already, create your Prescription object by following [these steps](https://app.gitbook.com/@medable/s/cortex/~/drafts/-MiXWFUncft4ttvEK-ld/cortex-guide/data-model-setup). If you haven't done so already, create the `Patient` property. Just scroll down below the list of standard properties and click on the `New Property` button. ![](https://files.readme.io/2e9b7c4-new-property.png) You'll then be presented with the new property screen. ![](https://files.readme.io/9944ad8-patient-property.png) ### ObjectId From the `Property Type` list, we'll select `ObjectId`. Then we'll be presented with more options particular to the ObjectId property. ![](https://files.readme.io/2c40e1c-Screen_Shot_2018-05-16_at_7.14.34_PM.png) 1. For `Source Object`, select "Account" and we will select `Indexed`. 2. Click `Create Property`. {% hint style="info" %} You could also select Reference as the property type and set the same values for `Source Object` and `Indexed`. ObjectId properties are lighter weight, but Reference properties have the advantage of allowing expansion into the referenced object instance. {% endhint %} ### List After creating the Patient ObjectId property, you will see it appear in the `Custom Properties` List. Now that that is in place, we need to create the list property on the account. Head back to Settings > Objects and click on the "Account" object. Then scroll down and click "New Property". Name it "Prescriptions" and select "List" as the property type and "Prescription" as the source object. We give it a plural name because this property will return a list of Prescriptions related to this patient Account. ![](https://files.readme.io/4241a5a-Screen_Shot_2018-05-16_at_7.23.38_PM.png) The only other option we need to set is the "Linked Property" option. In this case, set it to the Patient (c\_patient) property we created a moment ago. Then save the new list property. Ultimately what this list equates to is something similar to the following query: ``` GET /c_prescriptions?where={"c_patient":"575f58281d0c03a53ccc3ac6"} ``` But as a list property, we don't have to make that separate request, we can just get our accounts and pass in an `?include=c_prescriptions` and we'll get the prescriptions right in the response with our accounts like so: {% tabs %} {% tab title="Request" %} ``` GET /accounts?include=c_prescriptions ``` {% endtab %} {% tab title="Response" %} ```javascript { "data": [ { "_id": "575f58281d0c03a53ccc3ac6", "access": 6, "c_prescriptions": { "data": [ { "_id": "577c883c6f3035ee08357dfa", "access": 7, "c_date": "2016-07-01", "c_dispense": 60, "c_patient": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "c_provider": { "_id": "5771495a1d0c03a53ce83f1a", "object": "account", "path": "/accounts/5771495a1d0c03a53ce83f1a" }, "c_refills": 3, "c_rx": "Doxycycline 100mg tab. Take one PO bid.", "created": "2016-07-06T04:25:32.558Z", "creator": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "favorite": false, "object": "c_prescription", "owner": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "shared": false } ], "hasMore": false, "object": "list" }, "created": "2016-06-14T01:04:40.888Z", "email": "john@newhealthco.com", "favorite": false, "key": { "fingerprint": "73ad85a0-31cc-11e6-ba07-3f24c7443557", "secret": "PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp" }, "locale": "en_US", "locked": false, "mobile": "+15555555555", "name": { "first": "John", "last": "Smith" }, "object": "account", "roles": [ "000000000000000000000004", "000000000000000000000007", "000000000000000000000006" ], "shared": false, "state": "verified", "updated": "2016-06-14T01:08:06.647Z", "updater": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" } } ], "hasMore": false, "object": "list" } ``` {% endtab %} {% endtabs %} # Read and write data After we've completed setting up the object classes and their properties , we are ready to start reading and writing data in the format we just specified. More specifically, we'll create instances of the Prescription class in the Medable cloud. The following examples use HTTP. This is most applicable for web development. You might issue these HTTP requests using a tool like Fetch or Ajax. If you're doing iOS or Android development, we wrote SDK's that make it easier for you to interact with these endpoints. ## Create Creating prescriptions is a simple matter of a `POST` request to the object route. {% tabs %} {% tab title="Request" %} ``` POST https://api.dev.medable.com/{{your_org_name}}/v2/c_prescriptions ``` {% endtab %} {% tab title="Body" %} ```javascript { "c_rx":"Doxycycline 100mg tab. Take one PO bid.", "c_dispense": 60, "c_refills": 3, "c_date":"2016-07-01", "c_patient":"575f58281d0c03a53ccc3ac6", "c_provider":"5771495a1d0c03a53ce83f1a" } ``` {% endtab %} {% tab title="Response" %} ```javascript { "_id": "577c883c6f3035ee08357dfa", "access": 7, "c_date": "2016-07-01", "c_dispense": 60, "c_patient": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "c_provider": { "_id": "5771495a1d0c03a53ce83f1a", "object": "account", "path": "/accounts/5771495a1d0c03a53ce83f1a" }, "c_refills": 3, "c_rx": "Doxycycline 100mg tab. Take one PO bid.", "created": "2016-07-06T04:25:32.558Z", "creator": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "favorite": false, "object": "c_prescription", "owner": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "shared": false } ``` {% endtab %} {% endtabs %} Following this process using the WAPI would look like this: {% hint style="info" %} Change the account IDs for*`c_patient` and `c_provider`* to match those in your org. {% endhint %} ![](/files/-Mj66VBo4JmXlNAtlbjd) ## Get Many To get that prescription we just created back, we can simply do a `GET` request. {% tabs %} {% tab title="Request" %} ``` GET https://api.dev.medable.com/{{your_org_name}}/v2/c_prescriptions ``` {% endtab %} {% tab title="Response" %} ```javascript { "data": [ { "_id": "577c883c6f3035ee08357dfa", "access": 7, "c_date": "2016-07-01", "c_dispense": 60, "c_patient": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "c_provider": { "_id": "5771495a1d0c03a53ce83f1a", "object": "account", "path": "/accounts/5771495a1d0c03a53ce83f1a" }, "c_refills": 3, "c_rx": "Doxycycline 100mg tab. Take one PO bid.", "created": "2016-07-06T04:25:32.558Z", "creator": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "favorite": false, "object": "c_prescription", "owner": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "shared": false } ], "hasMore": false, "object": "list" } ``` {% endtab %} {% endtabs %} ## Get One Or to get a specific Prescription we can do the following `GET` request. {% tabs %} {% tab title="Request" %} ``` GET https://api.dev.medable.com/{{your_org_name}}/v2/c_prescriptions/{{object_id}} ``` {% endtab %} {% tab title="Response" %} ```javascript { "_id": "577c883c6f3035ee08357dfa", "access": 7, "c_date": "2016-07-01", "c_dispense": 60, "c_patient": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "c_provider": { "_id": "5771495a1d0c03a53ce83f1a", "object": "account", "path": "/accounts/5771495a1d0c03a53ce83f1a" }, "c_refills": 3, "c_rx": "Doxycycline 100mg tab. Take one PO bid.", "created": "2016-07-06T04:25:32.558Z", "creator": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "favorite": false, "object": "c_prescription", "owner": { "_id": "575f58281d0c03a53ccc3ac6", "object": "account", "path": "/accounts/575f58281d0c03a53ccc3ac6" }, "shared": false } ``` {% endtab %} {% endtabs %} {% hint style="info" %} For more on CRUD operations on objects, see [Cortex API Reference](/cortex-api/cortex-api). {% endhint %} # Making a Request When making Cortex API requests, the following are required * API Endpoint * API Client Key ## API Endpoint Requests must be made over https. The API endpoint takes the following form: `https:////v2/` Where: * `org_environment_endpoint` is the proper API endpoint for your org environment * `org_name` is the name you provided when signing up * `api_resource` is the Cortex API resource you are accessing. This could be a Cortex object or a custom route. For example, if your org name was newhealthco and you were accessing the Organization Object in your Cortex dev environment, your fully formed endpoint would look like: ## Request Headers All API calls require the Medable-Client-Key header, this is populated with an API Key that is generated when you create your app in Cortex. To create your API key, see `Generate API Key`. Additionally, if you configure your app with CSRF protection, a Medable-Csrf-Token will also be required. In this case, each authenticated request will return an HTTP response header of the same name, and the subsequent request must contain the value of that response header. | Header | Value | | ------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Medable-Client-Key | API key. See Generate API Key | | Medable-Csrf-Token | When app configured with CSRF protection, authentication and request to authenticated routes will produce a "medable-csrf-token", which must be sent as a request header with each subsequent call. | {% hint style="info" %} You must ensure that withCredentials is set to true. Otherwise the secure cookie will not be set on your browser. If you're using one of our mobile SDK's, all of this is handled for you. {% endhint %} {% tabs %} {% tab title="Example Request (AJAX)" %} ```bash Example GET /accounts/me $.ajax({ url: "https://api.dev.medable.com/example/v2/accounts/me", type: "GET", contentType: "application/json; charset=UTF-8", dataType : "json", xhrFields: { withCredentials: true }, headers: { "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq", "Medable-Csrf-Token": "MvFkpcS0BCM9qpf4K0pFMyiE57e3VtI5Cb38NfQn6eWiPPp6CqZCOOrAljDZYWnU" } }); ``` {% endtab %} {% tab title="Example Request (Fetch)" %} ```bash var request = new Request('https://api.dev.medable.com/example/v2/accounts/me', { method: 'GET', credentials: 'include', headers: new Headers({ 'Content-Type': 'application/json; charset=UTF-8', 'Medable-Client-Key': 'GsAqlhnIMzrDeD8V2MBQWq', 'Medable-Csrf-Token': 'MvFkpcS0BCM9qpf4K0pFMyiE57e3VtI5Cb38NfQn6eWiPPp6CqZCOOrAljDZYWnU' }) }); ``` {% endtab %} {% endtabs %} ## Request Methods ### GET `GET` requests let you read one or many instances of a resource. They typically take one of two forms **List (Many)** \`GET /\`\` **Read (One)** `GET //` `GET ///` ### POST `POST` requests allow you to create a new object instance from the request body. If the request is applied to an array property, the new array elements are pushed onto the existing array. **Create** ``` POST / { c_property1: 'value', c_property2: true, c_property3: [1, 2, 3] } ``` **Push** ``` POST // { c_property3: [4, 5, 6] } ``` ### PUT `PUT` requests allow you to update an existing object instance with the contents of the request body for the provided object instance \_id. If the request is applied to an array property, the entire array is replaced with the request body. **Update** ``` PUT // { c_property1: 'new value' } ``` ### PATCH `PATCH` requests let you chain operations together on an object instance in one request. For example, if you have an object instance that you'd like to update the value of one property (ordinarily a `PUT` request), push a value into an array property (ordinarily a `POST` request on a path), and delete another property (ordinarily a `DELETE` request on a path), that would take three requests. However, with a `PATCH`, you can achieve this in one request containing three operations. **Patch** ``` PATCH // [{ op: 'set', value: { c_property1: false } },{ op: 'push', path: 'c_array', value: 5 },{ op: 'unset', value: { c_property1: 1 } }] ``` **Patch Operations** | Operation | Description | | --------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | set | Update the value of a document or property json { op: 'set', path: 'c\_property1', value: 'new value' } OR json { op: 'set', value: { c\_property1: 'new value' } } | | unset | Delete a property or properties from the instance. json { op: 'unset', value: { 'c\_property1': 1, 'c\_property2.c\_sub\_property1': 1 } } | | push | Push a value or array of values into an array property json { op: 'push', path: 'c\_property3', value: \[4, 5] } OR json { op: 'set', value: { c\_property3: \[4, 5] } } | | remove | Remove a value or array of values from an array. If a value exists multiple times in the array, all values will be removed. json { op: 'remove', path: 'c\_property3', value: \[1, 3] } OR json { op: 'remove', value: { c\_property3: \[1, 3] } } | ### DELETE `DELETE` requests allow you to delete the object instance for the provided object \_id `DELETE //` For additional examples and details on making Cortex API requests, see First API Request Request Size Limit The default maximum request size is 1,024 Kilobytes Timestamp # Handling responses ## Making Requests All API calls require the `Medable-Client-Key` header. An Organization creates one or more applications, providing the public key to all its clients. Note that some web applications may employ the `Medable-Csrf-Token`. If an application is configured as such, each *authenticated* request must include HTTP response header of the same name, sent with the login response (and each subsequent authenticated response). {% hint style="info" %} For semantic reasons, API access to Objects is always through the use of the object plural name (e.g. /accounts). {% endhint %} ### Example: GET/accounts/me {% tabs %} {% tab title="JavaScript" %} ```javascript $.ajax({ url: "https://api.dev.medable.com/example/accounts/me", type: "GET", contentType: "application/json; charset=UTF-8", dataType : "json", headers: { "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq", "Medable-Csrf-Token": "MvFkpcS0BCM9qpf4K0pFMyiE57e3VtI5Cb38NfQn6eWiPPp6CqZCOOrAljDZYWnU" } }); ``` {% endtab %} {% tab title="Objective-C" %} ```objectivec [[MDAPIClient sharedClient] currentAccount:^(MDAccount* account, MDFault* fault) { if (fault) { // Fault handling } else { } }]; ``` {% endtab %} {% endtabs %} ## Handling Responses API responses always consist of JSON documents with an object property, whose values will either list or the name of the object type, such as `account` or `connection`. ### Example: Single Object Response ### GET/account ```javascript { "_id": "5516ee2634d8d93428169c0e", "object": "account", "roles": [ "000000000000000000000007" ], ... } ``` When the response is an array, the `data` property contains the resulting array, and the `hasMore` property contains a boolean value that is true if there are more results that can be retrieved using Paging. ### Example: Multiple Object Response ### GET /c\_examples?limit=1 ```javascript { "data": [ { "_id": "5519c01aae2fd2b02915c81f", "object": "c_example", "creator": { "_id": "5516ee2634d8d93428169c0e", "object": "Account", "path": "/accounts/5516ee2634d8d93428169c0e" }, ... } ], "hasMore": true, "object": "list" } ``` {% hint style="info" %} Lists are typically sorted by `_id`, in descending order. As such, results will have the newest items at the front of the result set. {% endhint %} If the response is a fault, the *object* property will be *fault* (see Faults). ### GET /accounts/5516ee2634d8d93428169c0e/profile/missing ```javascript { "object": "fault", "name": "error", "code": "kNotFound", "status": 404, "reason": "Property not found.", "message":"Resource not found.", "path":"profile.missing" } ``` Some responses, such as those retrieved via direct Property Access, will have `result` as their object property, as they do not represent a concrete, registered object type. Note, however, that directly accessed array properties will always be `list` objects. ### Result Example ```javascript GET /accounts/5516ee2634d8d93428169c0e/name { "object": "result", "data": { "first": "John", "last": "Smith" } } ``` ### List Example ```javascript { "object": "list", "data": [ "000000000000000000000007" ], "hasMore": false } ``` # Authentication ## Authentication Cortex employs session-based (using cookies) and signature-based authentication. Within each org, applications can be created which provide the necessary key and secret for API access. See Generate API Key for more details. ### Session-Based Authentication A typical use of session-based authentication would be for a client application, such as a mobile or web app, whereby individual users authenticate using their credentials to initiate a new session. The session is unique to the authenticated user and will timeout after a period of inactivity, based on org settings. Account registration or logging in both initiate authenticated sessions. When employing session-based authentication, Two Factor Authentication also applies. ### Signature-Based Authentication A signing key allows a third-party to make privileged calls to the API using a secure request signing mechanism. These keys can be configured for single or multiple user accounts, timed expiry, etc. Such a mechanism can be useful for scenarios such as back-end system integrations (e.g. Integrations with an EMR, or HL7 messaging appliance). ### Signed Request Headers | Name | Value | | ------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------: | | Medable-Client-Signature | The calculated request signature. | | Medable-Client-Timestamp | Client Unix Timestamp in milliseconds. The server issues a Medable-Server-Time responsed header with each operation which clients can use to synchronize. | | Medable-Client-Nonce | A client-generated nonce matching /^\[a-z\d]{16}$/i, used to prevent replay attacks. | | Medable-Client-Nonce | Optionally sets the calling principal by account id (if the app is configured to allow principal override). | ### Example signed request Node.js // Example signature-authenticated request using nodejs {% tabs %} {% tab title="node.js" %} ```javascript 'use strict'; function generateNonce() { var chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', maxC = chars.length-1, nonce = '', length = 16; while(length--) { nonce += chars[Math.round(Math.random() * maxC)]; } return nonce; } var crypto = require('crypto'), request = require('request'); var command = '/connections', // use only the path component (no query strings) method = 'GET', // uppercase http method apiKey = 'GsAqlhnIMzrDeD8V2MBQWq', apiSecret = 'Kzc8nwCQiKOgiwTIobaI3H6ryK4C5fC0QcYsuXCSbEMKcJPz8EU2phcj6akDB9VP', timestamp = Date.now(), hmac = crypto.createHmac('sha256', apiKey+apiSecret), signature; hmac.update(command + ';' + method + ';' + timestamp); signature = hmac.digest('hex'); var options = { url: 'https://api.dev.medable.com/example/v2/connections', headers: { 'Medable-Client-Key': apiKey, 'Medable-Client-Signature': signature, 'Medable-Client-Timestamp': String(timestamp), 'Medable-Client-Nonce': generateNonce() } }; request(options, function(error, response) { // ... }); ``` {% endtab %} {% endtabs %} ## Authentication ### Token Authentication and Scoping Applications can leverage JSON Web Tokens (JWT) to access Cortex. Once a key-pair has been generated, tokens can be generated from either session-based or signature-based apps. * To enable token signing, Generate RSA key pairs for each app you wish to authenticate by clicking the "Generate Key Pair" link in the right-hand column of your app. * The default limit of permanent/limited-use authentication tokens per account in the app is 10. * Check Expose Keys to add this app's JWK to the list produced in GET /auth/certs/\[jwk/pem]. Useful if you want third-parties to validate tokens generated by your app. To invalidate all tokens for an app you must regenerate the key pair or delete the app altogether. You can invalidate permanent/limited-use tokens per subject using Account.revokeAuthToken() and Account.revokeSubjectTokens(). Ephemeral tokens (those without a jti) can only be revoked by deleting the application or regenerating the key-pair. The following table outlines the JWT claim set supported in Cortex. | Claim | Description | | ---------- | :------------------------------------------------------------------------------------------------------------------------------------------: | | aud | The audience. This is always script.env.url | | iss | The issuing application's api key. | | iat | The unix timestamp when the token was generated. | | nbf | When present, the unix timestamp when the token becomes usable. | | exp | When present, the unix timestamp when the token expires. | | sub | The account identifier of the token's calling principal. The token will authenticate as this account when used with Cortex. | | jti | When present, represents the unique token identifier. This will exist for permanent and limited-use tokens. | | cortex/scp | The token scope. Scopes limit token access to sections listed in the claim. | | cortex/rls | An array of roles granted to the token, and merged with the token subject's existing roles. | | cortex/skp | When set, the token skips access controls for the purpose of limiting matches. The scripting analogue to this claim is skipAcl . | | cortex/skc | When set, the token skips access controls for instance creation. The scripting analogue to this claim is bypassCreateAcl . | | cortex/gnt | When set, the token grants this level of access to any and objects accessible to the token. The scripting analogue to this claim is granted. | | cortex/cnt | When set, represents the maximum number of times the token can authenticate before invalidating. | ### Scoping Scoping allows you to limit access to a subset of functionality, like object access, deployments, script and view execution, and administration functions. All access tokens are scoped, and adding scope is done by adding one or more scope chains to the token in the `cortex/scp` claim, or inheriting them from subject roles and those added with `cortex/rle` claims. Valid scope examples: * object.read.account.\*.name * script.execute (same as script, script.execute.\*) * view\.execute.c\_daily\_report Invalid scope examples: * object.read.account.name (missing identifier or \* before property) * deployment.create (use object.create.deployment instead) Scope Chain Level | Claim | Description | | ---------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | \* | The token can perform all operations as the calling subject. | | object \[*, create, read, update, delete] \[*, object\[#type]] \[\*, identifier] \[fqpp] | Object operations, such as reading accounts, creating connections, etc. The last element in the chain (fqpp) can be used to limit access to individual properties (e.g. c\_set\[]#c\_foo.c\_string\_arr\[]). You can see the fqpp (fully-qualified property path) in your schemas (GET /schemas). Examples:object.read.c\_step\_response#c\_boolean. *.c\_value allows reading c\_value from all c\_step\_response objects of the c\_boolean type. object.*.c\_comments.5953f7dc749219f1a2eee1ee allows full access to a specific instance of c\_comments (assuming the subject principal already has access). | | script \[*, execute] \[*, route, runner] \[identifier] | This scope is required if the token is used to run script routes or use the ad-hoc script\_runner system route. For routes, an Identifier can be added to the chain to limit use to a single route. | | view \[\*, execute] \[code, identifier] | This scope is required if the token is used to run script routes. An Identifier can be added to the chain to limit use to a single view. | | deployment \[\*, execute] \[identifier] | This scope is required if the token is used to execute deployments via scripted deployment automation.An Identifier can be added to the chain to limit use to a single deployment. | | admin \[\*, read, update] | This scope is required if the token is used to call administrative routes, such as user provisioning, deactivating accounts, etc. | Scopes in Views Views execute without scope; only view\.execute.\[view name] is required to run a view, supporting object.read scopes are not required. However, any other claims (grant, skipAcl, roles, etc.) are still applied. {% hint style="info" %} Views execute without scope; only view\.execute.\[view name] is required to run a view, supporting object.read scopes are not required. However, any other claims (grant, skipAcl, roles, etc.) are still applied. {% endhint %} Scopes have been added to custom roles. Tokens inherit the scopes from roles held by the principal, as well as any roles granted by the cortex/rls claim. In the image below, the Scoped role add the ability to execute any view and a single scripted route. ### Create Token Example {% hint style="info" %} When making requests using JSON Web Tokens (JWT), the Medable-Client-Key header is not required as it is embedded in the token. You may still send the client key header without issue provided it matches the client key used in the creation of the token. If it does not, a key mismatch error will be returned. {% endhint %} {% tabs %} {% tab title="Server-Side Access Token Creation Example" %} ```javascript const Account = org.objects.account; const account_id = Account .find({email: 'sample@medable.com'}) .skipAcl() .grant(4) .next() ._id; // create an ephemeral token that allows the caller to act as account_id and // read the account name and the subject of all c_message instances, skipping // access control. return org.objects.account.createAuthToken( 'yk8XJmrMKWzhinCl4Ww99A', account_id, { scope: [ `object.read.account.${account_id}.name`, "object.read.c_messages.*.c_subject" ], skipAcl: true, grant: consts.accessLevels.read } ) ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Client-side authenticating with JWT (nodejs)" %} ```javascript 'use strict'; const request = require('request'), token = 'eyJhCiJSUz...c4DiCkVvNA', options = { url: 'https://api.dev.medable.com/example/v2/c_messages', headers: { Authorization: `Bearer ${token}` } }; request(options, function(error, response) { // ... }); ``` {% endtab %} {% endtabs %} # Two-factor authentication ## Authentication Medable employs session-based (using cookies) and signature-based authentication. Within each org, applications can be created which provide the necessary key and secret for API access. For more information on Cortex authentication, see Authentication As one of the many technical safeguards built into Medable, two-factor authentication helps ensure security and compliance so as a user you can be sure no one can gain access to your sensitive data and as a company, you can be sure that your users are who they say they are. ### How does it work? Two-factor authentication is automatic and always on. When Medable detects that a user is authenticating from a new location or device, a verification code is sent to the mobile number for that user. The user simply has to provide that authentication code to be authenticated and for the new location or device to be verified. The process looks like this:![](https://files.readme.io/ab243a0-2fa-flow.png) An example of this in use can be seen right from the login screen for your org's control panel. Here we'll attempt to login to the control panel from a new device. ![](https://files.readme.io/410b305-login-first-time.png) However, Medable detects that we're logging in from a new location so authentication doesn't happen. Instead we're presented with the same login form but a new field to enter in our verification code.![](https://files.readme.io/777427a-login-form-2fa.png) Checking our mobile device, we receive the verification code via SMS.![](https://files.readme.io/d5e558d-verification-sms.png) We simply have to enter that code into the login form and now we're able to sign-in.![](https://files.readme.io/d6492e6-login-form-2fa-filled.png) ### As a developer, how do I enable 2FA in my app? You don't have to do anything to enable 2FA in the API. It works automatically when a user authenticates. However, you do want to be sure to build in the right interface and user-experience in your app for 2FA exception handling. When authenticating via the API, if 2FA is initiated, you will receive a `kNewLocation` fault in the response: ``` POST /accounts/login ``` Request Body: ``` { "email":"john@newhealthco.com", "password":"This is not the password!" } ``` Response Body: ``` { "object":"fault", "name":"location", "code":"kNewLocation", "status":200, "message":"A new location has been added to the account. Please verify it" } ``` At this point the user will be sent their verification code via SMS. You can use the `kNewLocation` fault to trigger your UI to present the user with the verification code field. Then, the token will need to be passed in the second authentication request: ``` POST /accounts/login ``` Request Body: ``` { "email":"john@newhealthco.com", "password":"This is not the password!", "location": { "verificationToken": "638393" } } ``` Response Body: ``` { "_id":"575f58281d0c03a53ccc3ac6", "object":"account", "created":"2016-06-14T01:04:40.888Z", "updated":"2016-06-14T01:08:06.647Z", "updater":{ "_id":"575f58281d0c03a53ccc3ac6", "object":"account", "path":"/accounts/575f58281d0c03a53ccc3ac6" }, "access":6, "favorite":false, "email":"john@newhealthco.com", "name":{ "first":"John", "last":"Smith" }, "mobile":"+15555555555", "locale":"en_US", "state":"verified", "locked":false, "key":{ "fingerprint":"73ad85a0-31cc-11e6-ba07-3f24c7443557", "secret":"PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp" }, "roles":[ "000000000000000000000004", "000000000000000000000007", "000000000000000000000006" ], "shared":false } ``` With location.verificationToken sent, the location is verified and authentication is successful. Future authentication attempts from this location will not require 2FA. ### How does this impact user experience? Two-factor authentication does require the user to take an extra step in order to authenticate. However, most users rarely run into it in day-to-day use. This is because when a user registers their account, the device they register from is automatically verified. So if the user typically uses the app on one device, 2FA will never be initiated. Only if the user logs in from a different device or deletes and re-installs the app will the 2FA process initiate. It's also important to note that this extra step is there to help ensure that the user's data is secure. Often when this added level of security is explained to users, it is seen as a positive. Typically the only users that are negatively impacted by 2FA are developers since developers often need to test apps from multiple accounts and devices. Because of this, we allow for bypassing 2FA by adding email address for developers to the `Location Verification Bypass` setting under `Settings > Organization` in the control panel (see [Organization Settings](https://docs.medable.com/docs/%base_url%25/general/org_settings) for more info). # Set third-party cookies Medable's session authentication requires session cookies. However, for a web app such as this, these cookies are considered 3rd-party cookies and some browsers don't allow for these types of cookies to be set without modifying security settings. Primarily this applies to Safari (including mobile Safari) and IE Edge. However, there's a simple solution to this issue involving an invisible iframe. ## 1. Create a custom route We're going to create our first custom script - a route that we navigate to from an invisible iframe in the web app to allow Medable to set an auth cookie on the browser. 1. Go to your org control panel 2. Click `Settings > Scripts` and click `New Script` 3. Match the configuration to the image below ![](https://files.readme.io/0eb7b65-Screen_Shot_2018-11-13_at_9.16.26_AM.png) The script you want included is the following. The only modification you make is the loginURL. ``` const res = require('response'), loginUrl = 'https://www.theurlyouwanttoredirectto.com' res.write('This is a test') ``` Next, we include the invisible iframe on our login page. ```