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

[LeanZubrezki]

Just replied and sent a quick Loom showing the problem, I am not actually using the example code so I think there is something else going on :frowning:

[goksan]

Is there any UI for viewing/deleting base webhooks? I might have missed it.

Looks like OAuth apps can’t list/delete webhooks created by other apps (which is great and how it should be)

Personal access tokens can list/delete all webhooks so I could hack something together if necessary.

[Sean_Keenan]

@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.

---

That's a good point, I've updated the documentation to make this a bit clearer (expect the update to be live in about a week) highlighting that you can also get all of the UserId's via the scripting extension and automations.

While it's true you can get UserId's via other surfaces (like the collaborator field), these don't provide all of the user id's in the base. Most of the time you shouldn't need additional information because the response also includes the User Mentioned object, which includes the relevant information about the user, like the display name and email address (the same information included in the collaborator field object). The one exception is when making comments, in which case getting the list of available users from other surfaces can be valuable.

[Artur_Mkrtchya1]

@SeanKeenan@Will_Powelsoncurrently we can't programatically create tables with fields like formula or lookup any idea when those would be supported ? without them it's very limited. Thanks!

[Artur_Mkrtchya1]

@SeanKeenan is there an endpoint to pass the token and retrieve the auth scopes ? something like token info that googlesheet and others have ?

[Artur_Mkrtchya1]

@Sean_Keenan we are getting the following error message:

You have reached the maximum access authorizations for this integration. You cannot authorize this integration again until you revoke at least one of the authorizations

What does it mean ? what  are the limitations ?

Can't we our OAuth integration to be used by 1000s of users ?

[Antony_Rappai]

Hi, this is good news, also is there a plan for implementing an endpoint to create snapshots? 

[Emma_Yeap]

Hi! I'm Emma, an engineer on the API team at Airtable who worked on this project. Going to answer a few related questions about personal access tokens vs OAuth vs API keys in this post:

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

Note: Kuovonne and I also chatted about this topic elsewhere, I'm posting a summary of our discussion here for public reference.

Today, the only way to set up third-party integrations is to give them your API key. Starting from this public beta, our recommendation is for third party integrations to use OAuth (i.e. they should not ask users to give them a personal access token or API key). This is for better security as well as a better user experience. OAuth gives the same benefits as personal access tokens in regards to having tokens with limited scope (declared by the developer) and limited base/workspace access that the user can control, plus additional security benefits for the user since they never have to copy and paste tokens manually, and because OAuth tokens expire and need to be refreshed (vs personal access tokens which never expire).

On the other hand, personal access tokens are for personal use - we describe this as “yourself, your client or for your company”.

This recommendation is documented on the personal access tokens guide and on the Authorization reference:

If you are building an integration that allow other users to grant your integration access to Airtable, you should instead create an OAuth integration.

This recommendation applies to both new integrations being built as well as existing integrations that use API keys. We've notified all current metadata API partners about these betas as well as the upcoming, planned deprecation of API keys, and we'll continue to be in touch with those partners as further details about the deprecation timeline are announced. We do know that migrating to OAuth takes time and work - the deprecation period for API keys will be at least 12 months, existing keys will continue to work through that time and so partners have that much time to migrate.

@Ruchika_Abbi1 : How does this impact platforms like Softr / StackerHQ? Does this mean they should be using tokens to connect to Airtable? Currently I create an “API user” account and then use the API keys for this account to connect to other platforms or for low code integrations through JS. Does it mean that going forward I should create a token and access the API’s through this token? Will there be a charge to these tokens?

@Artur_Mkrtchyan : Hi @Ruchika_Abbi1 thanks for your question… Old apps will continue working with api keys (no need to change in there… we will check if we can allow users to replace old keys with tokens) for the new Apps we will be using OAuth as it’s way better in many ways… We are now in evaluation step and will start implementing soon.

Thanks Artur! Adding on to Artur's response - yes, we are recommending that platforms like Softr / StackerHQ migrate to using OAuth, more detail in my reply above to Kuovonne's question.

We also see the more recent questions about OAuth implementation in this thread and we're checking with the team on getting answers for those!

[Emma_Yeap]

@Ava_Li : Hi! A quick question about the new PAT tokens (RAS syndrome ☹️ ). Do they expire after a set time? If not, what are the conditions for them to stop working and require regeneration? Are there plans in the future to implement a set expiration date? Also, slightly unrelated, do API keys expire?

Hi @Ava_Li ! Personal access tokens do not expire after a set time. You can delete them or regenerate them manually from /create/tokens. Implementing a set expiration date is something the team has discussed but is not currently on our roadmap.

API keys do not expire, but can be similarly cleared or regenerated from /account.

[Fred_Zhao]

---

@Kamille_Parks: Is there any thought on adding the ability to create new Views via the Web API (or Scripting/Blocks APIs)?

@Ambroise_Dhenai: Would it be possible to add to the Metadata API a read on Automations? So as to be able to extract the configuration of an automation (especially for documentation purposes, Changelog, etc.). Thanks !

@Artur_Mkrtchya1: currently we can't programatically create tables with fields like formula or lookup any idea when those would be supported ? without them it's very limited. Thanks!

@goksan: Is there any UI for viewing/deleting base webhooks? I might have missed it.

Thanks everyone for asking about these potential capabilities! These features are not currently on our roadmap.

Some are quite nontrivial to add: for example, when using airtable.com on the browser, views can have very complex conditions, formulas are checked for syntactic validity, and automations are even more complex, so we don't have immediate plans to expose these via the web API.

For exposing a UI to view/delete webhooks, since they're primarily developer-facing right now, we don't have plans to expose them via a UI.

The above being said, if you can share more details about what use cases you have in mind that can be unlocked by them, it would be helpful to inform our future plans!