인증

터미널에서 openemail login을 실행하면 어느 방식을 원하는지 묻습니다. 어느 쪽이든 로그인은 프로필로 저장되고, 이후의 모든 명령은 활성 프로필을 씁니다.

• —ai compose, ai summarize, MCP 명령은 브라우저 로그인만 쓸 수 있습니다.
• —브라우저 로그인은 선택한 승인이 만료되거나 로그아웃할 때까지 유효합니다. 키는 폐기될 때까지 작동합니다.

1. 1openemail login은 이 로그인을 위해 OpenEmail CLI on <your computer>라는 새 앱을 등록하고, 브라우저에서 OpenEmail 승인 페이지를 엽니다. 브라우저가 열리지 않으면 출력된 링크를 쓰세요.
2. 2필요하면 로그인한 뒤 워크스페이스, CLI가 받을 권한(읽기, 읽기와 보내기, 전체, 또는 직접 고른 권한), 닿을 도메인이나 주소, 승인 유지 기간을 고릅니다.
3. 3승인합니다. 브라우저가 승인을 알아서 터미널로 돌려주므로 탭을 닫아도 됩니다. CLI는 누구로 로그인했는지, 워크스페이스, 승인 만료 시점을 출력합니다.

openemail loginopenemail login --scopes emails:send,threads:readopenemail login --profile work

• —CLI는 승인을 10분 동안 기다립니다. 승인 페이지에서 나중에를 고르면 로그인이 취소되고 종료 코드는 10입니다.
• —--scopes는 승인 페이지에서 권한을 미리 선택하며, 그곳에서 바꿀 수도 있습니다.
• —프로필에 이미 로그인이 있으면 터미널에서는 바꾸기 전에 묻습니다. 무인 실행에서는 --force나 --yes를 주지 않는 한 거부합니다. 브라우저 로그인을 바꾸면 이전 로그인은 폐기됩니다.

내부적으로는 MCP 서버가 쓰는 OAuth 흐름입니다. PKCE를 쓰는 공개 클라이언트, 일회용 코드, 한 시간 유효하고 자동으로 갱신되는 액세스 토큰입니다. 브라우저는 임의의 포트에서 127.0.0.1로 돌아오며, 그곳에서는 이 로그인의 코드만 받습니다.

이 컴퓨터에서 브라우저를 열 수 없으면 CLI는 대신 링크를 출력합니다. SSH, CI, 디스플레이 없는 Linux, 또는 --no-browser를 준 경우입니다. 아무 기기의 브라우저에서 링크를 열고 승인하면, 페이지에 로그인 코드가 표시되고 이를 터미널에 붙여 넣습니다.

$ openemail login --no-browserOpen this link in a browser on any device to sign in:  https://api.openemail.uk/auth/mcp/authorize?response_type=code&client_id=…Paste the code from your browser

• —코드는 링크를 출력한 로그인에만 쓸 수 있으므로 다른 탭의 코드는 거부됩니다.
• —브라우저가 도착한 주소 전체를 붙여 넣어도 됩니다.
• —터미널이 없으면 코드를 stdin으로 넘기세요.

API 키로는 스크립트가 브라우저 없이 로그인하며, 코드를 요구받지 않습니다. 설정 → API 키(openemail open api-keys)에서 스크립트에 필요한 범위만 가진 키를 만드세요. CLI는 저장하기 전에 GET /keys/self로 키를 확인하며, oe_live_와 oe_test_ 키를 받습니다. 테스트 키로 보낸 메일은 절대 배달되지 않습니다.

openemail login --with-token < ~/.config/openemail/keyecho "$OPENEMAIL_KEY" | openemail login --with-token --profile ciopenemail login --token oe_live_…

--token도 되지만 키가 셸 기록에 남으므로 CLI가 경고하고 --with-token을 권합니다. 키를 저장하지 않고 쓰는 방법은 두 가지입니다:

• —환경의 OPENEMAIL_API_KEY는 이를 보는 모든 명령이 저장된 어떤 프로필보다 먼저 사용합니다.
• —--api-key <key>는 그 명령 하나에만 쓰입니다.

자격 증명이 둘 이상이면 다음 중 먼저 오는 것이 이깁니다: --api-key, OPENEMAIL_API_KEY, --profile로 지정한 프로필, OPENEMAIL_PROFILE로 지정한 프로필, 그다음 활성 프로필.

프로필은 어느 쪽이든 저장된 로그인 하나입니다. 첫 프로필의 이름은 default입니다. --profile로 더 로그인하고 서로 전환하세요:

openemail login --profile workopenemail profile listopenemail profile use workopenemail inbox --profile defaultOPENEMAIL_PROFILE=work openemail statusopenemail profile currentopenemail profile remove work

• —profile list는 각 프로필을 종류, 워크스페이스, 사용자나 키와 함께 보여 주고 활성 프로필을 표시합니다. 그 JSON에는 토큰이나 키가 절대 들어가지 않습니다.
• —profile current는 stdout에 이름만 출력하므로 스크립트에서 $(openemail profile current)가 동작합니다.
• —profile remove <name>은 openemail logout --profile <name>과 같습니다.
• —프로필 이름은 영문자, 숫자, 점, 대시, 밑줄로 최대 64자입니다.
• —profile use는 profile switch라고도 씁니다. 활성 프로필을 제거하거나 로그아웃하면 활성 프로필이 없어지며, 로그인이 필요한 다음 명령이 openemail profile use <name>을 안내합니다.

저장된 프로필은 로그인한 API를 기억하며, 그 자격 증명은 그곳으로만 보내집니다. 다른 오리진을 가리키는 --base-url이나 OPENEMAIL_BASE_URL은 아무것도 보내기 전에 종료 코드 2로 명령을 멈추고, 그 오리진에 별도 프로필로 로그인하는 방법을 알려 줍니다.

openemail login --profile other --base-url https://api.example.comopenemail inbox --profile other

• —OPENEMAIL_API_KEY나 --api-key의 키는 저장된 프로필이 아니므로, --base-url이나 OPENEMAIL_BASE_URL의 오리진으로, 둘 다 없으면 https://api.openemail.uk로 갑니다.
• —자격 증명을 보내지 않는 명령은 어떤 프로필이 활성이든 --base-url과 OPENEMAIL_BASE_URL을 따릅니다. 일회용 받은편지함, 키가 필요 없는 메서드, docs, open이 해당합니다.
• —암호화되지 않은 http는 localhost, 127.0.0.1, ::1을 제외한 모든 오리진에서 종료 코드 2로 거부됩니다. 대상은 API, 웹 앱, 로그인, 토큰, 폐기 요청, 그리고 MCP 서버입니다. 그 밖에는 https를 쓰세요.
• —openemail api //example.com/x처럼 API 오리진을 벗어나는 요청 경로는 아무것도 보내기 전에 종료 코드 2와 invalid_path로 멈춥니다.

브라우저 로그인은 사용자로서 동작하지만, 어떤 권한을 고르든 앱에 절대 승인되지 않는 것이 있습니다:

• —API 키 관리. keys:write와 keys:manage는 절대 부여되지 않으므로, 키를 만들고 교체하고 폐기하려면 keys:manage를 가진 API 키나 웹 앱이 필요합니다. openemail me rotate는 호출에 쓰는 키를 교체하므로 API 키가 필요합니다.
• —결제, 그리고 워크스페이스 자체. 요금제, 청구서, 워크스페이스 만들기, 전환, 삭제는 웹 앱에서 합니다.
• —무료 주소. 앱은 비즈니스 워크스페이스에 대해 승인되며, 무료 주소가 있는 개인 워크스페이스는 절대 제시되지 않습니다. API와 같은 규칙입니다.
• —멤버와 역할. 승인이 워크스페이스 전체를 대상으로 할 때만 가능합니다. 일부 도메인이나 주소로 제한된 승인에서는 members:write와 roles:write가 빠집니다.

API 키에도 고유한 제한이 있습니다. ai compose, ai summarize, 그리고 config를 제외한 모든 openemail mcp 명령은 브라우저 로그인이 필요한 MCP 서버를 거치므로, 키로는 종료 코드 4로 멈추고 이유를 알려 줍니다.

브라우저 로그인에서는 몇 가지 변경이 웹 앱처럼 먼저 인증 코드를 요구합니다. CLI는 필요할 때 묻습니다. 여섯 자리 코드를 이메일로 보내거나, 2단계 로그인이 켜져 있으면 인증 앱의 코드나 백업 코드 중 하나를 요구합니다. 코드가 맞으면 명령이 실행되고, 그 로그인은 60분 동안 다시 요구받지 않습니다. API 키는 요구받지 않습니다.

$ openemail webhooks create --url https://acme.com/hooks/openemailWe emailed a code to a•••@acme.com.Verification code: 482913Verified. You will not be asked again for 60 minutes.

• —프롬프트에서 r을 입력하면 이메일을 다시 보냅니다. 틀린 코드는 남은 시도 횟수를 알려 줍니다.
• —코드가 받아들여지면 명령이 한 번 더 실행되며, 두 번 실행되지는 않습니다.
• —--yes는 삭제를 확인하지만 코드를 건너뛰지는 않습니다.
• —무인 실행(--json이나 --no-input, CI, 터미널 없음)에서는 코드를 입력할 사람이 없으므로 명령이 종료 코드 4로 멈추고 아무것도 바꾸지 않습니다.
• —코드는 5번까지 시도할 수 있고, 다섯 번째로 틀리면 CLI가 새 코드를 제안합니다. 각 로그인은 1시간에 5개, 하루에 20개까지 코드를 요청할 수 있습니다.
• —한 로그인에서 24시간 안에 틀린 코드가 10개가 되면 그 인증이 일시 중지됩니다. 그러면 CLI는 언제 다시 가능한지 알려 주고, 다른 코드를 제안하지 않은 채 종료 코드 4와 step_up_paused로 멈춥니다. 이를 설명하는 이메일에는 앱 이름이 적혀 있습니다.

스크립트나 AI 클라이언트가 민감한 일을 하기 전에 openemail verify를 실행하세요. 지금 코드를 묻고, 이후 60분 동안 그 프로필의 모든 명령이 코드 없이 실행됩니다. openemail mcp call과 로컬 MCP 브리지도 포함됩니다.

openemail verifyopenemail verify --statusopenemail verify --status --jsonopenemail verify --force

• —브라우저 로그인의 액세스 토큰은 한 시간 유효합니다. CLI가 만료 전에 갱신하고 새 토큰을 저장하므로 알아챌 일이 없습니다.
• —각 리프레시 토큰은 한 번만 쓸 수 있습니다. CLI가 교체한 지 30초가 지난 옛 토큰이 쓰이면, 예를 들어 다른 컴퓨터에 복사한 config.json에서 쓰이면, 서버는 그 로그인을 완전히 폐기합니다. 파일을 복사하지 말고 컴퓨터마다 로그인하세요.
• —승인은 승인 페이지에서 고른 기간 동안 유효합니다. 기간이 끝나거나 계정 → 연결된 앱에서 앱이 제거되면, CLI는 더 이상 사용자로서 동작할 수 없고 openemail login을 다시 실행하라고 안내합니다.
• —openemail logout은 브라우저 로그인을 서버에서 폐기해 연결된 앱에서 없앤 뒤, 서버에 닿지 않더라도 이 기기에서 잊습니다. --all은 모든 프로필에서 로그아웃합니다.
• —API 키에서 로그아웃하면 여기서 잊을 뿐입니다. 키는 openemail keys revoke <id>나 웹 앱에서 폐기할 때까지 계속 작동합니다.

모든 것은 ~/.openemail, 또는 OPENEMAIL_CONFIG_DIR가 가리키는 폴더에 있습니다. 폴더는 본인만 읽을 수 있고(0700), 그 안의 모든 파일도 마찬가지입니다(0600). 각 파일은 임시 파일에 쓴 뒤 이름을 바꿔 제자리에 두므로 충돌이 나도 반쯤 쓴 파일이 남지 않고, 모든 변경은 잠금 파일 아래에서 이루어지므로 나란히 실행되는 명령이 프로필을 잃지 않습니다.