
The short version first: after over two years of operating Xkit, we're shutting down as of December 16, 2022.

## What happens to Xkit customers?

We individually notified existing Xkit customers of our decision to discontinue the service a bit over a month ago. Customers will need to find alternative vendors to help with their SaaS integrations or build the integrations themselves. To that end, we've exposed an [API endpoint to export credentials](https://docs.xkit.co/reference/list-credentials) from Xkit.

Since Xkit has always operated as a pure technology provider, your relationships with your customers and partners will be unaffected.

## Why are you shutting down?

Simply put, we didn't find a large enough market to build a venture-backed business in this space. We made a number of mistakes along the way, the subject of other blog posts for another time, but fundamentally, SaaS integrations embedded into a product is a smaller market than we anticipated. Our focus in one specific area, CRM, enabled much more traction, but also narrowed that market.

From a practical business perspective, we didn't start this business or run it in a manner consistent with this smaller market. In straightforward terms, we were built as a venture-backed business and spent money like one, but without the market to back it up.

## What's next?

We're winding down operations for our customers and then will wind down the corporate entity. We've already been working with our employees to find them new opportunities at other companies.

We're extremely grateful to the companies that trusted Xkit with their integrations over the years, from our original OAuth credentials product launched in August, 2022 to our unified CRM API launched earlier this year. It was a privilege to work with you and solve your problems. We're disappointed that we won't be able to continue that work together.

As Xkit's founder, I hope I'll get a chance to try again in the future with another startup, but until then I'll be around on Twitter: [@tgriff3](https://twitter.com/tgriff3).

Trey


Xkit is shutting down


Pulling objects from an API for the purpose of data synchronization adds some unique requirements to how an endpoint should work: the API should allow the clients to continuously fetch only the new changes while making sure that performance stays consistent regardless of the amount of data.

The simplest approach would be to use page numbers backed by some variant of `OFFSET ... LIMIT` query. While this is a popular choice, we can do much better than that.

Throughout this guide we’ll build an endpoint for fetching customer data (contacts) from an imaginary CRM system.

Note: the guide describes how to build a JSON-based RESTful API with a relational database as the underlying storage, but the ideas should translate to other technologies.

## The client’s perspective

Let’s see how an ideal API would work from the client’s perspective. The clients will start by building the initial URL to request the first page of results:
```
GET https://api.acme-crm.com/contacts
```

We also want to let them start from any point in time:

```
GET https://api.acme-crm.com/contacts?after=2022-01-01T00:00:00Z
```

The response will contain the actual data with the information about the paging:

```
{
  "contacts": [
    ...
  ],
  "page": {
    "has_more": true,
    "next": "/contacts?after=..."
  }
}
```

The clients will then use the `has_more` attribute to decide if they want to ask for more data immediately or delay the next request to preserve the API quota. Make sure to limit the amount of requests per minute and respond with [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) as needed.

From this point on, the clients will use the `next` attribute to build the URL to the next page of data:

```
GET https://api.acme-crm.com/contacts?after=...
```

This process will continue indefinitely.

In this approach the client-side implementation is straightforward and allows the clients to be as efficient as possible - a contact is returned by the API more than once only if it ever gets updated.

## Server-side implementation

Before jumping into the implementation, we need to address the following case. Imagine a situation where 15 contacts have the same modification timestamp and we want to fetch a page of 10 items. Which contacts should we pick?

We’ll solve this by using the contact’s unique ID as a tie-breaker when the timestamps are equal: we’ll sort the contacts by their modification timestamp first and then by their unique ID. This way, we retain the modification order while making sure that we always know which contact comes before. This also means that we need to add another parameter to the query:

```
GET https://api.acme-crm.com/contacts?after=2022-01-10T12:00:00Z&after_id=3712
```

We’ll see how it’s used when we build our query. Now we’re ready to follow the steps listed below.

### Step 1: Track modification time

We’ll ensure that we track the last modification time of a contact. The timestamp should include the timezone information:

```
{
  "id": 3712,
  "updated_at": "2020-01-05T10:30:15Z",
  ...
}
```

Every time the contact is updated, the "updated_at" field needs to be modified as well.

We’re using the extended ISO 8601 format which supports higher precision (like milliseconds) if needed. The timestamp could also be expressed as a [Unix time](https://en.wikipedia.org/wiki/Unix_time), e.g. 1578220215. Consider using the precision of at least seconds for either type.

### Step 2: Enable performant queries

We’ll add an index on the contacts table to make the querying faster:

```
CREATE INDEX contacts_paging ON contacts (updated_at, id);
```

### Step 3: Fetch the querying params

As we’ve seen earlier, we need to support the following URLs:

```
https://api.acme-crm.com/contacts
https://api.acme-crm.com/contacts?after=2020-01-05T10:30:15Z
https://api.acme-crm.com/contacts?after=2020-01-05T10:30:15Z&after_id=3712
```

Let's fetch the query parameters and provide default values for them:

```
after = params["after"] || "1970-01-01T00:00:00Z"
after_id = parse_int(params["after_id"]) || 0
```

We’ll also allow the clients to set the page size within some limits:

```
limit = ensure_between(parse_int(params["limit"]) || 100, 1, 1000)
```

Note: for brevity we’re not showing the full validation of the incoming parameters, but you should make sure to gracefully handle missing, blank and malformed values.

### Step 4: Fetch the subset of the data

With the parameters in place, we’re ready to build the query. The query consists of three steps: filtering, sorting and limiting:

```
SELECT   *
FROM     contacts
WHERE    (updated_at = $after AND id > $after_id) OR (updated_at > $after)
ORDER BY updated_at, id
LIMIT    $limit;
```

Note how we’re both filtering and sorting the contacts by the two fields (timestamp and ID) before limiting the result set - all done in the same database query. This ensures that we only return contacts that were not returned by the previous fetch.

If you need to move parts of that logic into your application code, you need to make sure that the filtering, sorting and limiting are applied in the correct order, otherwise you’ll risk skipping some data.

*Important*: make sure to use the same precision when comparing timestamps. You can either expose the timestamp with the full precision in the API or truncate the column value when filtering:

```
WHERE (DATE_TRUNC('second', updated_at) = $after AND id > $after_id) OR (DATE_TRUNC('second', updated_at) > $after)
```

#### Extra step: improve performance

We can improve the query performance by avoiding using an `OR` condition. We can use the so-called row values:

```
SELECT   *
FROM     contacts
WHERE    (updated_at, id) > ($after, $after_id)
ORDER BY updated_at, id
LIMIT    $limit;
```

This has the same semantics as the query we used before: first compare by the updated_at, then by the id. For example, both of these conditions evaluate to `TRUE`:

```
SELECT
  (2022, 5) > (2020, 10),
  (2022, 5) > (2022, 1);
```

If your database does not support row values, you can still avoid an `OR` condition with a more complicated, but equivalent filter:

```
SELECT   *
FROM     contacts
WHERE    updated_at >= $after AND NOT (updated_at = $after AND id <= $after_id)
ORDER BY updated_at, id
LIMIT    $limit;
```

### Step 5: Return the results

Now we can provide the query with the parameters and run it:

```
contacts = run_query("SELECT ...", after: after, after_id: after_id, limit: limit)
```

Since the results come ordered from the database, we can just grab the last contact to get the next paging params:

```
has_more = array_length(contacts) == limit

next_after = after
next_after_id = after_id

if array_length(contacts) > 0 do
  last = array_last(contacts)
  next_after = last.updated_at
  next_after_id = last.id
end

next_page = "/contacts?after=#{next_after}&after_id=#{next_after_id}"

return {
  "contacts": contacts,
  "page": {
    "has_more": has_more,
    "next": next_page
  }
}
```

Note how we initialize `next_after` and `next_after_id`: if there are no updated contacts, the clients should make the exact same request.

#### Extra step: avoid querying for empty data

If there are 10 contacts and the page size is 10, the first call will return `"has_more": true` even though there are no more contacts. We can fix this by asking for an extra contact and doing more work when fetching:

```
extra_contacts = run_query("SELECT ...", after: after, after_id: after_id, limit: limit + 1)
contacts = array_take(extra_contacts, limit)
has_more = array_length(extra_contacts) == limit + 1
```

The rest of the code stays the same.

### Step 6: Handle aggregates

If our contact aggregates other objects we need to do some extra work. Consider the following example:

```
{
  "id": 3712,
  "updated_at": "2020-01-05T10:30:15Z",
  "addresses": [
   {
       "id": 6311,
       "street": "South Avenue",
       "primary": true
    },
    {
       "id": 6312,
       "street": "Central Avenue",
       "primary": false
    },
    ...
  ]
}
```

In this model a contact has multiple addresses. Imagine there’s an endpoint that allows modifying a specific address, like so:

```
PUT https://api.acme-crm.com/contacts/3712/addresses/6311
{"address": {... }}
```

We need to let the clients know that a change has been made to the contact. We can handle this in two ways:
- Make sure to transactionally update the updated_at field on the contact whenever an address is added, updated or deleted; or
- Provide a sync-friendly endpoint for the addresses; the endpoint must not be scoped by the contact ID and should instead include that ID in the payload:
```
  GET https://api.acme-crm.com/addresses

  {
    "addresses": [
    {
        "id": 6311,
        "contact_id": 3712,
        "updated_at": "2022-01-10T12:00:00Z",
        "street": "South Avenue",
        "primary": true
    },
      ...
    ],
    "page": {
      ...
    }
  }
```

Depending on the code organization and the tech stack used, one option might be easier to implement than the other.

## Wrap-up

By following this guide we’ve built an API that allows clients to continuously pull data without compromising the application performance. Now we’re ready to build some great integrations!


The Guide To Building Sync-friendly APIs



## You have Zapier-based integrations

If you’re building a B2B SaaS business, before too long you’ll start hearing requests from customers for integrations:

> This looks great, but can it connect to HubSpot?

> I love it, but my sales team won't use it unless it syncs with Pipedrive

> How quickly can you build a Zendesk integration?

The first tool in the B2B SaaS startup founder’s toolbox is an obvious one: Zapier. With Zapier (and similar 3rd party automation platforms) you can allow your customers to connect your app with thousands of others without doing extra work on your part. It’s a perfect solution!

## You want native integrations

And Zapier is a perfect solution, at first. But over time you’ll feel pressure to build the most popular of these integrations natively. That pressure usually comes from a few places:

### Increase activation
For customers that don’t already use Zapier, getting them to sign up for another service (when you’ve just convinced them to sign up for yours!) is a tall task, and can reduce activation of your app. Leaving your app at all tends to reduce activation, so keeping your integration native is a big boost.

### Increase retention
Integrations are a huge driver of customer retention, but that force isn’t as strong when the integration isn’t native.

### Enterprise demands‍
Larger or enterprise customers may flat out refuse to use Zapier or similar tools for their integration. For them, it’s native or bust.

## But your team doesn't have bandwidth
Your engineering team is probably dragging their feet, dreading the task of building a native integration when the Zapier integration works well enough. They know that building a native integration is going to take months to build and will be a constant time suck to maintain and handle edge cases. You can probably hear your engineers saying:

> Why can’t our customers just use Zapier?

We built Xkit to solve this exact problem. It allows you to build native integrations using your existing API so you can build your integrations quickly and focus on your core product.

## Easily convert your Zapier integrations to native integrations

After creating an Xkit account, the first thing you’ll do is select the **Source** of your customers’ data. We’ve already built connectors to the most popular data sources including HubSpot, Front, and Intercom, with new ones being released every month. In addition to configuring this source with your developer credentials (so you have a completely white-labeled experience for your customers), you’ll select the data that your app needs from that source. We’ve already done the work of determining what data is exposed by each API and how to get it - you just point and click.

If you’re converting a Zapier Zap, you’ll be selecting the app that serves as the Trigger of the Zap along with the data that the Trigger exposes.

![Xkit Screenshot for setting up Intercom as a developer](/blog/setup-intercom-developer-credentials.png)
*Configure your developer credentials for your integration*

![Xkit Screenshot for selecting Intercom data to sync](/blog/select-intercom-data.png)
*Select which data exposed by the API to consume*

Once you have a Source, you’ll need a **Destination**: a serverless function that tells Xkit where to send your data. This is usually an API endpoint that you already have.

Coming from Zapier, this is equivalent to the Actions that you defined on your Zapier app. The biggest difference is that Xkit Destinations are meant to be used by your team internally instead of by your customers directly.

![Xkit Screenshot for creating a Destination](/blog/create-destination.png)
*Write a serverless function to send integration data to your API*

With both a Source and a Destination defined, all that’s left is connecting them together. Since you’ve already selected the data you need from your Source, as well as the data your Destination expects, connecting these together is as simple as mapping the data from your Source to your Destination. This mapping is usually easy enough that you don’t even need an engineer to do it (but you can also drop down to code if you need to).

In Zapier, this is most similar to defining a Template, but since this is a native integration, you need to do this only once for all of your customers to benefit from it!

![Xkit Screenshot for mapping Intercom data to the Destination](/blog/map-intercom-data.png)
*Map the data from your Source to your Destination*

Once your sources and destinations are connected, the last step is getting your users to authorize your native integration. To do that, you use xkit.js, our front-end SDK to embed a drop-in authorization experience, like Plaid Link.

![Screenshot of a user providing authorization to access Intercom](/blog/intercom-authorization.png)
*Get authorization from your users, right in your app*

That’s it! You’ve now converted one of your most popular Zapier integrations to a native integration, and you can reap the activation and retention benefits without bearing the engineering costs.

If you want to start converting your Zapier integrations into native integrations, get a demo of Xkit today!


Turn your Zapier integrations into native integrations with Xkit



If you're building a Zendesk integration that allows your users to connect their Zendesk accounts to your app, you have probably noticed that all the Zendesk documentation for OAuth use the domain `{subdomain}.zendesk.com`, and you might be asking: whose subdomain is this? Is it the app developer's or the user's?

> The subdomain you use when developing OAuth apps for Zendesk is the user's subdomain

The answer is that it's the user's subdomain, not you, the developer's subdomain. If you're building the integration only for internal use, that's the same subdomain so it won't matter, but if you intend for other Zendesk users to make use of it (what Zendesk calls a "global OAuth client"), you'll need to use their subdomain.

## Why do I need the user's subdomain?
Why use the customer's subdomain? Zendesk's docs sum it up:

> Zendesk maintains separate logins for each Zendesk account or subdomain. When a customer signs in, they're signing into a specific Zendesk subdomain which carries over to OAuth. When a Zendesk account owner uses OAuth to authorize your service, they're authorizing the service for their subdomain.
The documentation can be a little bit confusing at times, using "your" subdomain at times when they mean "the user's" subdomain. Just know wherever you see `{subdomain}`, they're referring to your user, not you.

## How to get the user's subdomain
Now you might be wondering if Zendesk provides a sort of global subdomain that you can use where Zendesk either determines through cookies, or collects directly from the user, their Zendesk subdomain. The unfortunate answer here is no: you're left to your own devices to ask the user for their subdomain before sending them through the OAuth flow. You'll also need to hang on to this subdomain: it's used not only for the initial authorization request, but also the token request and API calls afterward.

You'll probably want to model your own user subdomain collection after Zendesk's login process pictured here:


![Screenshot of Zendesk collecting the user's subdomain](/blog/zendesk-domain.png)
*Zendesk's own subdomain collection screen*

## Conclusion
So if you're building a Zendesk integration, don't forget to build in subdomain collection to make sure you're making requests to the right domain.

Of course, if you don't want to bother building an entire subdomain collection flow, you can use [Xkit's Zendesk Connector](https://app.xkit.co/connectors/new/zendesk). It has built-in subdomain collection through a popup window and it will surface the subdomain to you with every access token it provides.

![Screenshot of Xkit's Zendesk subdomain collection screen](/blog/zendesk-xkit.png)
*Xkit's Zendesk subdomain collection popup*

With one API call you'll get everything you'll need to get access to your user's Zendesk account. And you can [get started in 30 minutes, for free](/pricing).


What domain do I use when setting up OAuth for Zendesk?


## Why doesn't my access token work?
If you're building a GitHub integration into your app that uses GitHub's OAuth authorization method (as opposed to their App authorization, which is similar but has important differences), you may have noticed that sometimes the scopes that your access token has been granted are different from what you requested. This can be a particularly difficult issue to debug since it usually rears its head when you're trying to use an API protected by one of the scopes you requested, but the API request fails for just one of your users. However, when you try to reproduce this issue, it seems to work just fine. What's going on here?

GitHub makes use of a little known part of the OAuth2 spec that allows the authorization server (in this case GitHub) to: "fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions". The way GitHub does this is by allowing your user to pick and choose which of your requested scopes to actually grant to your application through a process we call "line item grants".

As you can see, this is a completely valid use of the [OAuth2 spec](https://tools.ietf.org/html/rfc6749#section-3.3), but since most providers don't use this, you may not have been ready for it. But not to worry, while the spec includes the ability for the authorization server (GitHub) to ignore your scope, it does provide you some recourse: "if the issued access token scope is different from the one requested by the client, the authorization server MUST include the scope response parameter to inform the client of the actual scope granted."

## Verifying the Granted Scope
The scope parameter in the Access Token response (which you were probably ignoring until now) will contain the scope that your user actually granted you, and which you therefore actually have access to with your token. See [GitHub's docs about this process here](https://docs.github.com/en/free-pro-team@latest/rest/guides/basics-of-authentication#checking-granted-scopes).

Unfortunately, here's where GitHub goes off the rails. While GitHub allows you to specify the scope you want in your request by space-delimiting each scope string (e.g. read:org read:user), which matches the OAuth2 Spec, it returns scope by comma-delimiting the scope strings (e.g. read:org,read:user) in violation of the specification. Which means you may have to serialize and parse your scope using different patterns.

## Scope Normalization
In addition, GitHub transforms the scopes through a process called ["scope normalization"](https://docs.github.com/en/free-pro-team@latest/developers/apps/scopes-for-oauth-apps#normalized-scopes). Basically, they take your requested scopes and narrow them down to the smallest set of logical scopes that will be granted. So, for example, if you request the repo scope, but you also request public_repo and delete:repo, GitHub will return just repo, since the other requested scopes are already included in the repo scope.

The actual normalization process (which scopes are removed when requesting two or more) is only partially documented, but based on our reading of the documentation and subsequent testing, here's the normalization tree:

```
repo
┣ delete:repo
┣ repo:status
┣ repo:invite
┣ repo_deployment
┣ public_repo
┃ ┗ admin:repo_hook
┃   ┗ write:repo_hook
┃     ┗ read:repo_hook
┗ security_events
admin:org
┗ write:org
 ┗ read:org
admin:public_key
┗ write:public_key
 ┗ read:public_key
user
┣ read:user
┣ user:email
┗ user:follow
write:discussion
┗ read:discussion
write:packages
┗ read:packages
admin:gpg_key
┗ write:gpg_key
 ┗ read:gpgp_key
workflow
gist
notifications
admin:org_hook
```

## Conclusion
If you're building a GitHub integration, be sure to check the normalized, comma-delimited scopes that your user actually granted you via GitHub's API to make sure that your token has the scopes you expect it to.

Of course, if you want to avoid building (or heck, even learning) all that, you can use [Xkit's GitHub OAuth Connector](https://app.xkit.co/connectors/new/github-oauth) and be up and running with always-valid access tokens in a half hour. We have built-in checks to make sure that your tokens have the scopes you expect them to so you don't have to worry about it.


Why does my GitHub OAuth2 Token not have the scopes I requested?


Today I'm excited to announce the release of a new Xkit feature: the Connections Dashboard. Inspired by a dashboard that one of our customers built to make debugging customer issues easier, the Xkit Dashboard displays in one place the status of all of your users' connections.

That means you can see for every one of your users's which integrations they've enabled, which they haven't, and which ones they're having issues with. We have filters you can use to help you jump straight to problem areas.

![Screenshot of an error filter on the connections dashboard](/blog/user-dashboard-errored.png)
*The error filter lets you jump to problem connections faster*

## Friendly Names
As part of our dashboard rollout, we've added the ability to specify "friendly names" for your users, so instead of showing up in the dashboard as an opaque ID, you can use the user's email address or name to quickly spot them. Your customer support or success team can use the dashboard to debug issues for your customers that are having issues with integrations and walk them through re-connecting.

![Screenshot of a user's email address to identify connections](/blog/friendly-name.png)
*See a user's email address to quickly identify them and debug their issues*


## Works with Groups
The Dashboard also takes advantage of [Xkit Groups](/blog/company-wide-integrations-for-b2b-saas-user-groups) so you can see the status of connections across an entire group (perhaps your customer's organization, company, or project) to help them along in their onboarding and again to debug issues.

![Screenshot of Xkit's Group Connections Dashboard](/blog/group-dashboard.png)
*See the status of connections across a customer's team or organization*

## More to come
This Dashboard is the first, but not the last, tool we've released designed to help your customer support and success teams debug issues. We have more tools on our roadmap to make your integrations more reliable and reduce the support calls you have to field.


Debug Integrations with the Xkit Connections Dashboard


If you're building a Salesforce integration into your app, particularly a "Connected App" style of integration, and your integration uses [OAuth to get access to Salesforce's REST APIs](https://help.salesforce.com/articleView?id=remoteaccess_authenticate.htm&type=5), you may be wondering when the access tokens issued by Salesforce expire.

According to the [OAuth 2.0 spec](https://tools.ietf.org/html/rfc6749#section-4.2.2) the `expires_in` parameter is included with the Access Token response and provides the lifetime of the returned token in seconds. And while this parameter is extremely common in OAuth implementations, it is merely *recommended* and not *required*. The Salesforce OAuth implementation does *not* use this parameter.

## Typical Token Expiration
In our experience at Xkit, Salesforce Access Tokens typically expire in 2 hours (7,200 seconds), but this value is not guaranteed to be static—Salesforce could change it at any time with no warning.

> Salesforce Access Tokens typically expire in 2 hours

## How to determine token expiration
So what do you do? You have two options:

1. Use your access token until you receive a 401 HTTP status code, and only refresh it then
2. Use Salesforce's token introspection endpoint to determine when the token expires

## Token Introspection
That's right! While Salesforce does not include an expires_in parameter, they do have a special token introspection endpoint as part of the [extension to the OAuth 2.0 spec](https://tools.ietf.org/html/rfc7662). This endpoint ([Salesforce docs here](https://help.salesforce.com/articleView?id=remoteaccess_oidc_token_introspection_endpoint.htm&type=5)) returns a JSON object that includes an `exp` property. This `exp` corresponds to the [`exp` claim of the JWT spec](https://tools.ietf.org/html/rfc7519#section-4.1.4). Unlike the `expires_in` parameter, `exp` is a Unix epoch timestamp.

Here's an example request from the Salesforce docs:

```
POST /services/oauth2/introspect HTTP/1.1
Host: https://mycompany.my.salesforce.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic M01WRzlsS2NQb05JTlZCSVBKamR3MUo5TExNODJIbkZWVlgxOUtZMQp1QTVtdTBRc
UVXaHFLcG9XM3N2RzNYSHJYRGlDUWpLMW1kZ0F2aENzY0E5R0U6MTk1NTI3OTkyNTY3NTI0MTU3MQ==

token=00DR00000009GVP!ARQAQE5XuPV7J4GoOu3wvLZjZI_TxoBpeZpRb6d8AVdII6cz
_BY_uu1PKxGeAjkSvO0LpWoL_qfbQWKlXoz1f2ICNiy.6Ndr&
token_type_hint=access_token
```

And an example response from our own experience:

```
HTTP/1.1 200 OK
Content-Type: application/json

{"active":true,"scope":"api refresh_token openid","client_id":"3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE","username":"user@example.com\",\"sub\":\"https://login.salesforce.com/id/000000000000000000/000000000000000000\",\"token_type\":\"access_token\",\"exp\":1610509606,\"iat\":1610502406,\"nbf\":1610502406}
```

## Conclusion
So if you need to know when your Salesforce Access Token expires, call the introspection endpoint and you can figure it out for yourself. And don't forget to add the special refresh_token scope so you can refresh your access when it does expire.

Of course, if you want to avoid building (or heck, even learning) all that, you can use Xkit's [Universal CRM integration framework](/) to build integrations that work across CRMs without ever worrying about access tokens.


When do Salesforce access tokens expire?


## Background: Why I had to pivot
Almost 3 years ago I incorporated Kinesis Inc, the corporate entity behind [Xkit](https://xkit.co/). But at the time I was building a non-custodial cryptocurrency exchange. After going through Y Combinator and raising $3.5M from some great investors and building a product I was really proud of, I made the hard decision to shut it down nearly a year ago. We hadn't found an audience that would provide venture scale growth, so it was back to the drawing board.

I started working on an idea in FinTech, trying to help a friend's company solve a problem with SMB customers not paying on time (or at all) for their services. As I talked to prospective customers about the problem, one thing became abundantly clear: in the time that I had spent away from the SaaS world toiling in the Bitcoin mines, expectations around how SaaS tools work together had radically shifted. It was no longer a "bonus" that you worked with some of their other tools, it was an outright necessity. For the product I was exploring I would be building integrations with Quickbooks, Xero, Stripe, and a few others.

I asked around if anyone had any good tools to accelerate this process, but the responses I got back were pretty disappointing. Nearly every tool was focused on consumers of SaaS software plugging together the services that they used. Not nearly as much was out there for producers of SaaS software trying to build native integrations to the other tools their customers use. Not only that, but the ones that did exist tried to pretend that we live in a world where powerful integrations are easy to design and maintain with a GUI. While I'm a fan of no-code and low-code solutions, the fact remains that for some tasks, leaning on a software development lifecycle is still the most effective and efficient way to build it.

In the meantime, the US blew up with COVID, throwing the financial markets (which my new FinTech project was heavily dependent on) into turmoil. So like any good (read: desperate) startup founder, I scrapped the FinTech project and started building the tool that I wish had existed to help me build integrations to my prospective customers' other SaaS apps. And despite never having touched the language, I decided to build it in Elixir.

## Choosing Elixir
I've spent most of my career as a software engineer writing in Javascript and Ruby. I've long been intrigued by the concepts behind functional programming (years ago I wrote a small toy to try to achieve immutability on the web, like a centralized IPFS), and a friend introduced me to Elixir, which incorporated some Ruby syntax, making it a bit friendlier to get started with.

The concepts behind Erlang/OTP/Elixir make it a great fit for a tool like the one I was building. I knew it would be heavily dependent on outside services, meaning it had to be robust to crashes and other unforeseen events. And I knew high concurrency and low latency would be important features as a piece of developer infrastructure. I also wanted to test out [Paul Graham's theory of hiring programmers](http://www.paulgraham.com/pypar.html): choose a good language and great programmers will always want to work for you. And finally, I'd be lying if I said there wasn't a part of me that just wanted to try something new. I had spent the past two years working an idea I had to shut down, my "big pivot" was a non-starter, I had laid off nearly the entire team, and for product development it was just me in my bedroom. So I liked the idea of learning something new while working on my second pivot in 3 months.

## Learning Elixir
I read through Elixir's fabulous language guide. I mean I really read it, cover to cover, and did pretty much all the examples as they came up. Then I read through a handful of pages in the Phoenix (the most popular web framework for Elixir) guides before I said "f*** it" and started building what became Xkit. My first commit was on May 14, 2020. Commit message: "Initial install with platforms".

The first week was rough. I wasn't used to moving this slowly, but not only was a learning a new language with features pretty unfamiliar to me like pattern-matching, I was learning a new paradigm. Javascript is whatever you want it to be, which means I had some exposure to FP incidentally, but almost everything I've spent significant time on has had a pretty object-oriented flavor to it, even dating back to when I first got started with PHP. Not to mention the entire ethos of OTP to "fail fast and noisily" which ran counter to so many experiences which focused on avoiding failure at all costs (yes, I've seen some pretty large try/catch blocks in my day). I got pretty discouraged at the pace I was moving, and somewhere about 10 days in I was really regretting not just using Node/Express, a stack I was so familiar with it felt like I could write the app in my sleep.

But I kept at it (probably more out of pride than anything else) and a few days later I felt things start to shift. I still wasn't moving fast, but I could tell I was improving. Things that only a few days ago had felt foreign and impossible to grasp started to make sense. From that point on I started accelerating, and on June 1st, I sent one of my investors this video showing the first version of what became Xkit.

<iframe width="300" height="150" src="https://www.youtube.com/embed/7dJi3sAsHM0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Shortcomings of Elixir and Phoenix
I started off trying to use a pure Phoenix stack including their new real-time front-end, LiveView. I'll be honest, although I really like Elixir and Phoenix, using Phoenix for the front-end brought me back a bit to my Rails days, and not in a good way. Building a modern web application with those tools felt like I'd be working against the tide. I also am pretty partial to [Evergreen](https://evergreen.segment.com/), the React UI kit by Segment, and I was bearing down on the 6 week timeline I'd set for myself to launch this product. So I ripped out the Phoenix front-end and converted it to be a back-end only application and built a new front-end in React and Evergreen. I did end up using Phoenix's websocket implementation which was a big help integrating the two, although some pieces are not very well documented.

When I finally getting close to launching, I ran up against the greatest weakness of my choice to use Elixir: deployment. While the world has moved towards a serverless paradigm, Elixir/Erlang/OTP thrive by handling a lot of the same things that "serverless" promises. That means that to really take advantage of all it has to offer, you're better off deploying it on as close to bare metal as you can. That, in addition to some of the architecture choices I made with Xkit (specifically to provision a custom subdomain for every user), made deployment quite a challenge. Failing to find any good documentation about how to deploy a Phoenix application on AWS, I ended up [writing a blog post about our process](https://xkit.co/post/deploying-phoenix-for-elixir-on-aws-ec2).

You might think it's overkill for a one-person development team to have a one-command deploy process, but I assure you, based on my past experience, it's well worth the effort. You don't want critical DevOps knowledge in one person's head, or worse, on some inscrutable AWS GUI. I want it all in code. Even today, you can take the entire Xkit stack, move it to a new AWS account and have it up and running with a single command in around 30 minutes.

## Launching Xkit
The delays I hit caused me to miss my six week launch goal by two weeks: I launched to some fellow YC founders on July 12 with \~15 connectors and this video. Two weeks after that I launched on [Product Hunt](https://www.producthunt.com/posts/xkit) and shortly after that on [Hacker News](https://news.ycombinator.com/item?id=24121290) with over 25 connectors. Since then we've worked with some really great early customers who have helped us refine the product, and I've been able to hire a few friends to help grow the business.

<iframe width="300" height="150" src="https://www.youtube.com/embed/7MqwQ3Czejs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

We're well over 50 connectors at this point (almost entirely driven by customer requests) and we add so many that we no longer track it as a metric. And while I'm still contributing code, I can safely say that the majority of the coding that I will do for Xkit is now likely behind me. But the process of building Xkit (and learning Elixir in the process) has been incredibly rewarding, and hopefully we're just getting started.

PS - In case you're wondering about the answer to PG's theory about language being a good hiring tool - my early results indicate that it is. From a single post on [Elixir Forum](https://elixirforum.com/) I met one of the best engineers I've seen, and a few weeks later he recruited one of the best engineers he'd worked with to join the team.


Pivoting with Elixir


**Note: This blog post refers to a deprecated method of setting up Xkit. Refer to the [current docs for the latest method](https://docs.xkit.co/docs/xkit-contexts), which is still compatible with FusionAuth.**

FusionAuth and Xkit came together for this blog post to share how you can use our services to boost your engineering team’s productivity. If you’re working on growing your SaaS business, you know just how much your engineers have on their plates. At both FusionAuth and Xkit, we believe that outsourcing what you can – like authentication and integration infrastructure – lets your team focus on the products and services that drive your business.

We’ve written this post to lay out how you can use our services together to simplify your auth and build native integrations into your app faster. No more telling your customers that the integrations they’ve been asking for are “on the roadmap”. Follow the steps below and you can ship them in no time.

## Xkit and FusionAuth integration
### Install FusionAuth
FusionAuth offers [a number of different methods you can use to install the service](https://fusionauth.io/docs/v1/tech/installation-guide/). Once you’ve installed it, there’s a Setup Wizard to walk you through the next steps. You’ll need to create your application in the FusionAuth interface and then add a few elements to your application code base to fully implement the FusionAuth login flow. A [full, detailed setup guide](https://fusionauth.io/docs/v1/tech/5-minute-setup-guide/) is also available. Feel free to create additional [users via the FusionAuth administrative user interface](https://fusionauth.io/docs/v1/tech/core-concepts/users/).

Once FusionAuth is installed and configured, you have a full featured user management system, ready to go. APIs to control everything, multi factor authentication, consent management, SAML, OIDC, and more, hosted wherever you want. There’s also FusionAuth Cloud, a managed services offering, if you don’t want to host FusionAuth yourself.

### Install Xkit
After you’re set up with FusionAuth you’ll want to head over and [create your Xkit account](/pricing). Upon sign-up, Xkit will also prompt you with some basic information needed to set up the environment.

To set up Xkit in your code base, you’ll need to add the script tag for xkit.js on your front-end:

```
<script src="https://<your-slug>.xkit.co/xkit.js"></script>
```

In addition, your users need a place to actually sign in to their apps. The easiest way to do this is to direct users to the hosted integration catalog Xkit has set up for you:

```
<a href="https://<your-slug>.xkit.co">Integration Catalog</a>
```

Alternatively, if you need more customization, you can embed Xkit’s catalog on your site and customize its styling to fit your look and feel ([details here](https://docs.xkit.co/docs/self-hosted-catalog)). If you still need more flexibility, you can use our SDK.

### Connect FusionAuth with Xkit
Now that you have both FusionAuth and Xkit set up, you’ll need to connect the two. We do this by collecting some information from your FusionAuth dashboard and inputting it into Xkit.

Specifically, you’ll need to generate an RSA key and then add your `iss` claim, `aud` claim and JWKS URL into your Xkit account. This setup is [fully documented](https://docs.xkit.co/docs/fusionauth).


![The generated RSA key for use with Xkit.](/blog/fusionauth-rsa-keypair.png)

Once you’ve done that and clicked save, FusionAuth and Xkit will be connected.

You can now have your users log in using FusionAuth’s Login API. You’ll get a JWT from FusionAuth on successful user authentication. This JWT can then be sent to Xkit to authenticate the user in Xkit, and therefore grant them access to integrations you’ve configured.

In your code base you can log your user into Xkit simply by using your FusionAuth ID token:

```
//...
xkit.ready(() => {
  xkit.login('eyJhbGciOi...')
})
//...
```

This easy JWT-based connection saves you the trouble of dealing with API keys and provisioning users for Xkit; you can instead maintain them in FusionAuth. You can also use FusionAuth for all your other applications, providing one view of all your users.

Note that the JWT is available in the DOM, and therefore exposed to cross site scripting attacks, should any malicious JavaScript be executed on the same page. To minimize the risks, lock the permissions associated with this JWT down and don’t allow its use as a bearer token for any other more sensitive APIs or services.

## Add an integration
Now to actually set up your first integration! Say you want your users to be able to connect their Trello accounts with your app. To do this, you’ll first need to register your app with Trello and get a [Trello API key](https://trello.com/app-key).

![The Xkit Trello integration screen.](/blog/xkit-trello-screenshot.png)
Next you’ll need to add Trello as a connector in your Xkit platform and provide Xkit with the Trello API key you received after registering the app. After filling out a bit more information in the Xkit Trello connector page to set the permissions you require and what your users see when they’re connecting the app, you’ll click save.

You’re now ready to retrieve access tokens! You simply make one API call to retrieve a user’s fresh access token:

```
const trelloToken = await xkit.getConnectionToken("trello")
```

If the token isn’t available, you should send the user to the appropriate place in your integration catalog to connect it.

```
//...
if (!trelloToken) {
  window.location.href = xkit.connectorUrl("trello")
}
//...
```

Behind the scenes here, Xkit handles all the complicated parts of managing the access tokens — dealing with each SaaS app’s protocol differences, token expirations, refresh tokens, protection against CSRF attacks, token encryption and more — so that it’s as simple as one API call for you. This setup also makes it easy to retrieve the token anywhere in your stack, be it in Cloud Functions, on the front-end, from your web server, etc. You can then use the token to make calls to the Trello API.

To add integrations to other apps, you follow essentially the same steps and retrieve the token with the same API call. Specific guides for different apps [can be found here](https://docs.xkit.co/docs/connecting-with-apps-overview).

We’re always looking for feedback and suggestions so let us know your thoughts! Thanks for reading.

*This post was co-written by FusionAuth and Xkit. It can also be found on FusionAuth's blog [here](https://fusionauth.io/blog/2020/12/09/xkit-and-fusionauth/).*


Adding native integrations to your app with Xkit and FusionAuth


If you're building B2B software that's used by an entire organization, the integrations you build take on a different character. Rather than convincing each individual user to connect your software to some service, you're dealing with the IT administrator and helping them get integrated as part of your onboarding process.

This style of organization-wide integrations is supported by major software vendors like Google and Microsoft, but it strays significantly from a typical OAuth2 authorization code flow that most of us are familiar with.

So when an early customer requested this style of organization-wide integration, we jumped at the chance to simplify the process of connecting B2B software to the accounts of an entire company.

And now we're publicly launching our Google Service Account and Microsoft Admin connectors!

## Google Service Accounts


Getting access to an entire company's Google Workspace (formerly G Suite) account can be a huge undertaking. In addition to the Service Account setup for the developer, it requires the IT administrator of the Google Workspace account to manually input the Client ID of your service account and all of the permissions you require. And since this entire process takes place out of band, you don't get any feedback on whether it's configured correctly. As you can imagine, this leads to confusion, support tickets, and ultimately, a delayed onboarding process for your product.

Once your customer is setup, the code on your end required to get access tokens is entirely different than a normal OAuth2 process for Google Accounts, and includes the need to pick a specific user to impersonate.

The new Xkit Google Service Account connector makes all that easy: just follow the [instructions for configuring a Google Service Account in Xkit](https://docs.xkit.co/docs/google-service-account-calendar) and Xkit handles the rest! We take the IT administrator through a guided flow to easily copy and paste the right values, and we test that everything was set up correctly. That means no need to have a special support article covering Service Accounts, and no need to handhold your new customer through setup. Your customers will get up and running in seconds with no support needed from you.

Not only that, but we handle token generation and refresh too. Every time you want to access the organization, you just make a request to Xkit and you'll have a functioning access token available to you without having to worry about how to generate them.

Google Service Accounts are designed for organization-wide access, which they accomplish through user impersonation. Xkit makes this easier for you in two ways:

1. We automatically include a Directory scope, so that you can use the Directory API to query for all of the users in a Google Workspace organization
2. [We let you specify which user you want to impersonate when requesting tokens](https://docs.xkit.co/reference/get-context-connection-by-slug)


```
curl --user publishable_key:secret_key \
  https://app.xkit.co/platform/contexts/{your_context_id}/connections/google-calendar-admin?provider_user_id=some.user@example.com
```


With these two in place, you can get access to any user in the organization, easily.

## Microsoft Admin Consent
Microsoft Graph takes a different (and simpler) approach to organization-wide access, which they call Admin Consent, Application access, or sometimes Service Accounts. You have to request a set of Application Permissions rather than Delegated Permissions, and it uses a separate endpoint to request admin consent. Once the administrator has consented, your application will get back only the ID for the organization that granted access, which you'll need to persist in order to request access tokens.

Again, with our new Microsoft Admin connector, you can skip all of that: our guide walks you through configuring your application with Microsoft, and from there it will feel just like any other Xkit connector. Your customer's IT Administrator user gets taken through a consent flow, and we'll generate tokens that you can request at any time.

## Xkit Groups
**Note: Xkit Groups has been replaced by [Xkit Contexts](https://docs.xkit.co/docs/xkit-contexts).**

Both of our new connectors work even better when paired with [Xkit Groups](https://xkit.co/post/company-wide-integrations-for-b2b-saas-user-groups). With Groups, your customers get a shared view of what's been connected, and you get access to a simpler, [group-wide API](https://docs.xkit.co/reference/get-context-connection-by-slug) that lets you get access tokens for anyone in the company. With organization-wide access granted via Google and Microsoft, and organization-wide tokens, you get an entire toolkit for building native B2B Saas integrations.

You can [start building for free](/pricing), and if you have other organization-wide connectors you'd like us to add, please let us know!


Organization-wide Access with Google and Microsoft


At [Xkit](/), we've long been fans of Vercel since its early days as Zeit. So when we had a few customers want to use Xkit in [Next.js](https://nextjs.org/) apps, we were happy to oblige. But since Next.js does things a little bit differently than a standard React app, our instructions didn't quite cut it.

So today we launched our [Next.js Sample app using an Xkit embedded catalog](https://xkit-next.vercel.app/). You can take a look at the open source repo or the [live site hosted on Vercel](https://xkit-next.vercel.app/). Feel free to clone the project, add your own Xkit domain, and use it as a starting point for your own Next.js app.


![Xkit Catalog embedded in a Next.js App](/blog/xkit-nextjs.png)
*Xkit Catalog embedded in a Next.js App*

## How it works
Here's what's happening in the app:

To use the embedded catalog React component, we do a dynamic import to only render it on the client. While xkit.js and xkit-catalog.js may eventually include native SSR support, for now they work only in the browser, so we need to exclude them from Next.js SSR:

```
const XkitCatalog = dynamic(
  () => import('@xkit-co/xkit-catalog.js').then(mod => mod.App),
  { ssr: false }
)
```

We also need to import createXkit so we can create our instance. Again, we only want to run this in the browser:

```
import { createXkit } from '@xkit-co/xkit-catalog.js'
const xkit = process.browser ? createXkit(process.env.NEXT_PUBLIC_XKIT_DOMAIN) : undefined
```

Now we're ready to use our component! In this example, we render our library on the index.js page. If it was on another page, we could adjust the rootPath attribute to reflect the current page.

```
<xkitcatalog xkit="{xkit}" connectorspath="/" hidetitle=""></xkitcatalog>
```

You'll notice we also set the connectorsPath to /. This means that when visiting a specific connector, like Clubhouse, the path will be /clubhouse. So we can create another Next.js page to render the right connector when visiting that page. In our example, we created [slug].js with the following contents:

```
import Home from './index'
export default Home
```

Since our index.js already renders the catalog, we can let the catalog use its current slug to determine which connector to render.

## Wrap-up
That's it! We now have a fully functioning Next.js app using Xkit's embedded catalog. And with the `xkit` instance we just created, we can use the full [xkit.js](https://docs.xkit.co/reference/xkitjs) functionality, including creating a user session, connecting apps, and retrieving access tokens or API keys.

If you're building a Next.js app and embedding Xkit, let us know! We'd love to highlight some users to showcase what's possible.


Add SaaS integrations to Next.js with Xkit


**Note: User Groups has been replaced by [Xkit Contexts](https://docs.xkit.co/docs/xkit-contexts), an even more flexible way to model your users on Xkit.**

Today we're launching a brand new feature to make managing integrations for your B2B customers even easier: User Groups.

## B2B integrations are Group integrations
If you're building a B2B SaaS product, the integrations that you're building are most often shared across the whole company: your customer has one Stripe integration, not one for everyone in the company.

This has been consistent feedback from our early customers: Xkit's integrations should align with the structure already in place in our user's apps. This is a classic case of ["your customer built your roadmap"](https://twitter.com/n2parko/status/1316799523189129216?s=20) as we have customers who have hacked together some code to loop over every one of their Xkit user to find a working integration - quite the hack.

## Launching Xkit User Groups
With the launch of Xkit User Groups feature, we can support the groups you already have in your application, natively within Xkit. After you turn on the "Use Groups" flag, you can assign your users into groups however you provision them (via API or via JWT). Once a user is assigned to a group, the status that they see on their [embedded integration catalog](https://docs.xkit.co/docs/self-hosted-catalog) will be the status of their group's connectors, not just their own. So now everyone in the organization will know if they connected to [Webflow](https://docs.xkit.co/docs/webflow). (and yes, this same status will show up if you use the [xkit.js SDK](https://docs.xkit.co/docs/custom-catalog) directly).

In addition to a better end-user experience, this feature also comes with a new [Groups API endpoint](https://docs.xkit.co/reference/get-context-connection-by-slug). With this API, you can fetch the current access token to any service for the entire group, just like you can with individual users.

## Get started with Groups
You can read the full documentation on how to use the new Groups feature here: [User Groups](https://docs.xkit.co/docs/user-groups).

But this is just the beginning: Groups lays the foundation for a bunch of new features that will help B2B SaaS products build integrations faster and more reliably while delivering an unmatched end user experience. Stay tuned!


Company-wide integrations for B2B SaaS with User Groups


Today we're launching a brand new feature to make building user-facing integrations easier: API Key integrations.

## API Keys are now as easy as they should be
For less mature APIs, which can include some of the newest and trendiest SaaS apps, you're often forced to use API keys to access them rather than a technology like OAuth2. When accessing a user's account on their behalf, this means teaching them how to get an API key, collecting the key from them, storing it (encrypted I hope!) and retrieving it later in the service where you need to use it.

We've heard from our early users about the pain this causes and their desire to integrate with these types of APIs. Now, with Xkit's API Key integrations, you can skip all those painful parts and go straight to the actual integration work. For the apps we've integrated, we have step-by-step instructions along with a video guide showing your users how to generate and store API keys **right in the UI**.

We test the keys against the API to make sure that they work before saving them, then we serve them up wherever you need them in your stack with one API call, just like we do with OAuth2 access tokens. And like all our tokens, they're encrypted and tightly access controlled. Now, no matter how an API does its authentication, you can get access to it with the same pattern, and your users get a consistent, easy-to-use experience.

## New App Support
We're launching this feature with 5 new apps that support API keys based on requests from our users:

- [Clubhouse](https://clubhouse.io/)
- [Monday.com](https://monday.com/)
- [Linear](https://linear.app/)
- [Postmark](https://postmark.com/)
- [SendGrid](https://postmark.com/)

## We want your feedback
We'd love to hear what you think about our new API key integrations, and if you're looking to integrate with an API with keys that we don't support yet, please let us know!


Connect to your users' apps using API keys


## Background and Overview
[Xkit](https://xkit.co/) is built on [Phoenix](https://phoenixframework.org/), the popular framework for the [Elixir](https://elixir-lang.org/) language (which in turn runs on the Erlang VM).

When it came time to deploy our application, we were deciding between Gigalixir, Heroku, and AWS. Ultimately, although AWS would be a little bit more complicated to deploy, for some of the things we wanted to do (subdomain for each customer, custom domain support, etc) AWS was the better choice.

We also decided we wanted to deploy directly onto the EC2 instance rather than running the deployment in Docker. In our view, OTP handles a lot of the same jobs that Docker does, so adding Docker into the mix (no pun intended) is adding indirection, maintenance, and potentially performance bottlenecks.

For building the release, we settled on Elixir Releases. These seem to be the "way of the future" when it comes to deploying Elixir applications, and we wanted to futureproof our infrastructure setup.

However, what we assumed to be a pretty common scenario of deploying an Elixir Release to EC2 seemed to be largely undocumented. So we built some tools ourselves, and thought we'd share them.

## Steps for Deployment
The following assumes that you have a Phoenix application on Elixir v1.9 or later that you're trying to deploy. It is based on the [Phoenix guide to deployment](https://hexdocs.pm/phoenix/releases.html) so its recommended that you read that to get an understanding of the steps we're doing here.

Throughout this guide, we'll denote variables that you're intended to replace with double brackets, like `{{ replace_me }}`. (yes, this comes from our use of Jinja2 within Ansible!)

### The Dockerfile
Elixir doesn't support cross-compilation, so to build an Elixir Release that targets Amazon Linux 2 for EC2, we either need to use another EC2 box to build our application, or use a Docker container.

We opted to use a Docker container so that we could keep our production box for use only in serving production traffic. We could have also spun up another EC2 instance to use just for building, but that felt like overkill.

The Dockerfile below targets Amazon Linux using the `amazonlinux:2` base image.

```
# Building an Phoenix (Elixir) Release targeting Amazon Linux for EC2
# By https://github.com/treygriffith
# Original by the Phoenix team: https://hexdocs.pm/phoenix/releases.html#containers
#
# Note: Build context should be the application root
# Build Args:
# OTP_VERSION - the OTP version to target, like 23.0
# ELIXIR_VERSION - the Elixir version to target, like 1.10.4
#
# If you have other environment variables in config/prod.secret.exs, add them as `ARG`s in this file

FROM amazonlinux:2 AS build

# https://gist.github.com/techgaun/335ef6f6abb5a254c66d73ac6b390262
RUN yum -y groupinstall "Development Tools" && \
    yum -y install openssl-devel ncurses-devel

# Install Erlang
ARG OTP_VERSION
WORKDIR /tmp
RUN mkdir -p otp && \
    curl -LS "https://web.archive.org/web/20211116200237/http://erlang.org/download/otp_src_${OTP_VERSION}.tar.gz" --output otp.tar.gz && \
    tar xfz otp.tar.gz -C otp --strip-components=1
WORKDIR otp/
RUN ./configure && make && make install

# Install Elixir
ARG ELIXIR_VERSION
ENV LC_ALL en_US.UTF-8
WORKDIR /tmp
RUN mkdir -p elixir && \
    curl -LS "https://web.archive.org/web/20211116200237/https://github.com/elixir-lang/elixir/archive/v${ELIXIR_VERSION}.tar.gz" --output elixir.tar.gz && \
    tar xfz elixir.tar.gz -C elixir --strip-components=1
WORKDIR elixir/
RUN make install -e PATH="${PATH}:/usr/local/bin"

# Install node
RUN curl -sL https://rpm.nodesource.com/setup_12.x | bash - && \
    yum install nodejs -y

# prepare build dir
WORKDIR /app

# install hex + rebar
RUN mix local.hex --force && \
    mix local.rebar --force

# set build ENV
ENV MIX_ENV=prod

# install mix dependencies
COPY mix.exs mix.lock ./
COPY config config
RUN mix do deps.get, deps.compile

# build assets
COPY assets/package.json assets/package-lock.json assets/
RUN npm --prefix ./assets ci --progress=false --no-audit --loglevel=error

COPY priv priv
COPY assets assets
RUN npm run --prefix ./assets deploy
RUN mix phx.digest

# compile and build release
COPY lib lib
# uncomment COPY if rel/ exists
# COPY rel rel
RUN mix do compile, release
```

If you have any compile-time configuration in environment variables (e.g. in `config/prod.exs`), you'll need to add them as `ARG`s to the Dockerfile. (As an example, we use compile-time configuration to specify the HTTP port).

This Dockerfile is designed to live in the root directory of your application. If you decided to put it elsewhere (e.g. in a `deploy` directory, like we do), make sure you set the build context to the application root.

### Building The Release
Now that we have our Dockerfile, we need to build and extract the Elixir Release.

First We need to grab our current OTP version:

*We use this version to download Erlang, so we need both the major and minor version. See this [StackOverflow answer](https://stackoverflow.com/questions/9560815/how-to-get-erlangs-release-version-number-from-a-shell/34326368#34326368) for more details about why this is the best way to get both.*

```
erl -eval '{ok, Version} = file:read_file(filename:join([code:root_dir(), "releases", erlang:system_info(otp_release), "OTP_VERSION"])), io:fwrite(Version), halt().' -noshell
```

and Elixir version:

```
elixir -e "IO.puts(System.version())"
```

Then we'll build the Docker image:

```
docker build -t {{ your_image_name }} \
                --build-arg OTP_VERSION={{ otp_version }} \
                --build-arg ELIXIR_VERSION={{ elixir_version }}
```

*Don't forget, if you have other compile time environment variables, you'll need to pass them in here*

With the Docker image built, we can create a temporary container and extract the release:

```
docker run --name {{ your_build_container }} {{ your_image_name }} sh
docker cp {{ your_build_container }}:/app/_build/prod/rel/{{ your_app_name }} ./temp
```

Now we've got an Elixir Release that targets Amazon Linux 2!

### Move to EC2 and Start
All that's left is actually starting up the release.

First, on your EC2 box, create a location for the release to live.

```
mkdir -p ~/app
```

Copy the new release to EC2 (this is from your local machine):

```
scp ./temp/{{ your_app_name }} ec2-user@{{ your_ec2_host }}:~/app
```

And start up the new release:

```
~/app/bin/{{ your_app_name }} daemon_iex
```

You'll need to run the `daemon_iex` command with whatever environment variables you're using in `releases.exs`, like `DATABASE_URL`.

## Wrap-up
With the steps above, you should be able to successfully deploy an Elixir Release for Phoenix to Amazon Linux on AWS EC2.

There are other steps to a successful deployment approach that we'll hopefully cover in future posts, such as:

- Configuring EC2 and Phoenix to use alternate ports for HTTP/S to avoid running as root
- Handling RELEASE_COOKIE
- Automating the release (via Ansible)

Happy deploying!


Xkit is shutting down

The Guide To Building Sync-friendly APIs

Turn your Zapier integrations into native integrations with Xkit

What domain do I use when setting up OAuth for Zendesk?

Why does my GitHub OAuth2 Token not have the scopes I requested?

Debug Integrations with the Xkit Connections Dashboard

When do Salesforce access tokens expire?

Pivoting with Elixir

Adding native integrations to your app with Xkit and FusionAuth

Organization-wide Access with Google and Microsoft

Add SaaS integrations to Next.js with Xkit

Company-wide integrations for B2B SaaS with User Groups

Connect to your users' apps using API keys

Deploying Phoenix for Elixir on AWS EC2

Xkit is shutting down