New Beta: New API authentication methods, endpoints, and public API docs

[SeanKeenan]

Hi everyone,

For those I haven’t met, I’m Sean, an engineer on the Airtable API team.

Today our team is excited to announce the public beta (it’s public – so no need to sign up!) of several new API authentication features to make our API more secure for all our users. Bundled with them are the (long-requested!) metadata API, comments API, and webhook API.

And one more feature (my personal favorite): a new publicly accessible API docs site to learn about all of these in more exciting detail! Airtable Web API

• API authentication: personal access tokens
  • Use personal access tokens for more granular control over access to bases and workspaces: https://airtable.com/create/tokens.
• API authentication: OAuth for Integrations
  • Register an integration to build using OAuth 2.0: https://airtable.com/create/oauth.
  • Users can authorize third-party integrations with OAuth for a secure setup and granular controls.
• New API endpoints
  • As part of either of the authentication methods above, we have several new API endpoints and functionality, including the metadata API - please read our changelog for more info on these endpoints. Airtable Web API
• Enterprise Admin features
  • Enterprise admins can create service accounts that can utilize both of the new API authentication methods and associated API endpoints described above. This feature will help ensure continuity for scripts and integrations.
  • Admins will also be able to restrict whether and which OAuth third-party integrations can be used in their enterprises.

Additionally, we plan to announce a deprecation timeline for user API keys when these more secure authentication methods (personal access tokens and OAuth integrations) graduate from public beta to general availability. Per our deprecation guidelines, there will be a notice period of at least 12 months (from the date of that future announcement) before the deprecation is enforced.

This public beta is just the beginning! We plan on continuing to add new features and update existing ones based on your feedback.

Learn more from our updated API docs and then try it for yourself — and, if you have any questions, don’t hesitate to ask here,

Sean, on behalf of the Airtable API Team

[kuovonne]

I find this support page about personal access tokens to be confusing. Here are the first two paragraphs.

Personal access tokens (now available to all users in open beta) are used to authenticate requests to Airtable’s API when developing an integration for yourself, your client, or for your company.

Personal access tokens act as your user account, and should be kept secret and not shared with any third-party services or integrations.

These two paragraphs are at odds with each other. The first paragraph says personal access tokens are for developing integrations. Yet the second paragraph says personal access tokens are not to be shared with integrations. How can one use a personal access token in an integration without sharing that token with the integration? The vast majority of integrations involve third party services.

[SeanKeenan]

ScottWorld:

I nominate @SeanKeenan for president!!

Thank you for your kind words Scott, it means a lot to the team (and me) - and it really has been a huge team effort, I’m just the one that made the post!!

Plus - you don’t want me running for president, if that happens you’ll have one less person working on Airtable! :stuck_out_tongue_closed_eyes:

[SeanKeenan]

kuovonne:

I noticed that the new name for this API is “Web API” versus “REST API”. Thanks for giving thought to the naming.

Especially with some API’s which aren’t quite “REST” (like webhooks) we felt it was the right time to update the name!

kuovonne:

SeanKeenan:

Enterprise admins can create service accounts

Where can we see the documentation for this, and how does this affect billing? Are service accounts “free” or will there be charges for service accounts?

Here is the help center article! They are free, however there is a limit to the number of service accounts allowed on an enterprise (limit is 30).

kuovonne:

Will Airtable also be generating a tool where we can see what services have been using an API key in the past month/year/time frame? People setup automations/integrations that use an API key, and then forget what those integrations are.

We’re still working through exactly what our plan will be, but wanted to give early notice as soon as possible. We hear you, rest assured that we will try to make this transition as seamless as possible!

kuovonne:

what is the motivation to use automations instead of webhooks?

One of the biggest differences is their form factor! Webhooks require more setup, hosting your own code, but allow more flexibility - or building external services. Automations have a powerful user interface, integrate with more than Airtable, and don’t require running your own servers (or even understanding code!)

kuovonne:

To clarify, this is a system where we can register a webhook that Airtable will call when the conditions are met? It looks like webhooks can detect the deletion of a record. Is this correct? It looks like webhooks can detect schema changes. Is this correct?

Yes to all of the above :tada:

kuovonne:

For example, are there limits on the number of times a webhook will be called? Other than the fact that webhooks only last for 7 days and there is a max of 10 per base

Those are the only limits, webhooks can also be refreshed anytime during those 7 days to reset this timeout.

[kuovonne]

SeanKeenan:

Webhooks require more setup, hosting your own code, but allow more flexibility - or building external services. Automations have a powerful user interface, integrate with more than Airtable, and don’t require running your own servers (or even understanding code!)

Thanks for this explanation.

Automations = low floor
Webhooks = high ceiling

Automations = configuration completely within Airtable
Webhooks = requires interactions “outside of Airtable” (typically a server, but could be a glue factory), a subset of the web API

Of course many of the features in webhooks are features that people on the floor would like to have in automations: access to previous record values, triggers for when records are deleted, triggers for schema changes. I am sure that Airtable knows that people want this.

[ScottWorld]

SeanKeenan:

Plus - you don’t want me running for president, if that happens you’ll have one less person working on Airtable! :stuck_out_tongue_closed_eyes:

Haha, great point! :rofl:

@SeanKeenan Question: The new API documentation for comments says that we can tag users by either email or User ID. But then it goes on to say that the User ID can only be retrieved by Enterprise users who are using the Enterprise API. This is actually not true… there are several different ways to retrieve the User ID through the API which do not require an Enterprise account.

[kuovonne]

ScottWorld:

But then it goes on to say that the User ID can only be retrieved …

Can you share a link where this is stated? I see that this page states that user IDs can be retrived via the Enterprise admin, but it doesn’t say that it is the only way.

Two other ways of getting user IDs are via automations with a collaborator field, or via scripting.

[ScottWorld]

There are at least 5 (and possibly more) ways of getting User IDs:

1. ALL USERS: By using Airtable automations or external automations.
2. ALL USERS: By writing Javascripts.
3. ALL USERS: By using the API to read a collaborator field.
4. ENTERPRISE USERS: By using the Get Collaborator API functions.
5. ENTERPRISE USERS: By exporting the Admin Panel.

kuovonne:

but it doesn’t say that it is the only way.

By omitting any reference to any other ways of getting User IDs, it strongly implies that it is the only way.

[LeanZubrezki]

So excited to see the metadata API see the light!!!

I have a question around the OAuth flow: is code_challenge_method required when doing the POST to https://airtable.com/oauth2/v1/token?

If it is, then it seems off the spec, is it possible to remove it as required?

I am using a third party for the integration which supports PKCE but they follow the spec and don’t send it and will be difficult to convince them to add it as it is off the spec.

As an example, I took a look at a major OAuth2 library (PassportJS) and it only sends the method in the authorization step, and only the verifier during token exchange.

[Will_Powelson]

is code_challenge_method required when doing the POST to https://airtable.com/oauth2/v1/token?

It should not be, thankfully I believe this is just an error in our docs (a fix is now incoming). Spec compliance is generally important to us so please reach out if you find similar errors.

[LeanZubrezki]

Thanks for the reply @Will_Powelson, this is the request with all the info, the only thing that comes to mind why it is failing is that code_challenge_method is required, can’t think of anything else.

[Album] imgur.com ...