Help for Alpine - XOAUTH2
You are in Home > Miscellaneous > XOAUTH2


  1. Introduction
  2. Setting Up Gmail
  3. Other Providers

Introduction to XOAUTH2

XOAUTH2 is a special way in which you allow a program access to your data. The idea of XOAUTH2 is to create the illusion of security by allowing only temporary access to a user to their own data.

The idea is simple. If a user can authenticate to a server, then that user is given a key that allows the user to create temporary passwords. These passwords are only valid for a short period of time and they must be renewed constantly in order for the user to keep having access to their data. This revalidation is done without the user noticing.

The key given by the server must be saved securely. If you share that key you are sharing access to your data, so all efforts must be made to keep that key secure.

Setting Up Alpine with Gmail

These directions are specific to setting up Alpine with Gmail. None of the other major vendors (Outlook, Yahoo!) have documentation on how to make XOAUTH2 work under IMAP, nor it is clear that it does work.

This implementation of XOAUTH2 supports access to and In particular, you must set your IMAP server using those server names.

If you want to use XOAUTH2 to authenticate to the Gmail server, you must set your inbox or incoming folder, and your smtp servers as follows

inbox: {}INBOX

here, is your id to login to gmail. For example it could be, or, if your company uses gmail as its email provider.

Now let's go through the one-time set up of XOAUTH2 in Gmail. First we assume you have already set up Gmail as your inbox or as an incoming folder.

The rest of the set up will happen once you try to open that folder. When you do that, you will see a long message in the screen, it looks as follows.

First Setup Screen

Looking at the screen, there are some commands in the menu. The one you will use to setup Alpine is the "C" command, to enter the code. If you do not wish to proceed, simply cancel by pressing "E" to exit. However, before you enter a code you need to get it from Gmail's servers. This is done by opening the URL that appears in the screen. Alpine will attempt to use your web browser to open that link, but you can use any browser. Since you will login into Gmail, you must open this link with a browser that supports Javascript. This is a requirement set up by Gmail, not Alpine. This might mean that persons with disabilities might need additional help to login to Google's servers.

If you open the link, you will see a normal login screen. Enter your login and password. Login Screen for Gmail

Once you complete loging in to your account, you will see the following screen

Warning from Gmail

What you are supposed to do is to click on the link at the bottom of the warning screen, and Allow Alpine access to your account. [1]

Once you click on Allow, you will be given a code. The image below shows part of a code. It is a long string, you probably will have a hard time trying to memorize it.

Code to Access Gmail

Copy this code, and return to Alpine. You will go back to the set up screen where you started this process. Now press "C". It will look as follows

Entering Code into Alpine Prompt

Paste the code into this prompt. You will see something similar to the following

Pasting the code

Finally, press Enter. Alpine will ask you if you want to preserve this code in your password file.

preserve code prompt

You must save this code somehow. It will be used to login into Alpine in the future. For example, when you login to Alpine the next day, or next week. Using your password file is the best way to preserve this code. Do not share it. Anyone who has access to this code could access your account.

You are done! Now you can login to your Gmail account using XOAUTH2. In the future you will not go through this process. Alpine will open your account as soon as you attempt to open your gmail account. (However, note that this code expires. If you do not access your Gmail account using Alpine for a long time, Google will expire this code, and you will have to go through this process again to get a new one.)

Also note that this set up is done on each device that you use Alpine. If you use Alpine in two different devices, you will have to go through this process in each device. Gmail keeps a record of the last 50 codes that it gives you before it deletes them or expires them. If you use one or two of them frequently, you will never have to generate a code again.

Setting up XOAUTH2 in other providers

Setting up Alpine with other providers (such as outlook, or Yahoo!, for example) is not possible at this time. I tried setting up Outlook, but I was unable to do so, even when I went through all the process they ask. I do not seem to be alone in this. It seems that Outlook does not allow XOAUTH2 access for imap. I do not know much about Yahoo!, I tried registering Alpine with them, but there is no documentation on how to do so.

[1] The text tells you that Alpine is trying to access your account. The name Alpine appears in blue. It is a link. If you click on it, you will see information on the developer

Information on the developer

return to top
You are in Home > Miscellaneous > XOAUTH2