API 키를 사용하면 개발자나 직접 운영하는 도구가 Mateflow Open API로 커뮤니티 데이터를 읽고 쓸 수 있습니다. API 키는 관리자 → 설정 → 통합 → API 접근에서 만들고 폐기합니다. 각 키는 하나의 커뮤니티에서만 작동합니다.
사용 가능한 사람: 소유자와 관리자. · 위치: 웹(관리 콘솔). · 플랜: API 액세스 사용 여부와 커뮤니티의 일일 API 요청 수는 플랫폼 플랜에 따라 다릅니다.
API 키는 커뮤니티별로 발급됩니다
API 키는 하나의 커뮤니티에 속하며, 키로 보낸 요청은 항상 그 커뮤니티를 대상으로 작동합니다. 여러 커뮤니티를 연결하려면 각 커뮤니티의 관리 콘솔에서 키를 따로 만듭니다.
크리에이터 대시보드(app.mateflow.com)에는 API 키가 없습니다. 대시보드에 있던 워크스페이스 단위 키는 커뮤니티별 키로 대체되었습니다. 대시보드의 커뮤니티 개요 페이지에는 해당 커뮤니티의 연동 페이지로 가는 링크가 있습니다.
API 키 만들기
- 관리자 → 설정 → 통합으로 이동하여 API 접근 탭을 엽니다.
- 새 키 생성을 클릭합니다.
- 키를 사용할 도구처럼 용도를 알 수 있는 키 이름을 입력합니다.
- 스코프 및 권한에서 통합에 필요한 권한에만 체크합니다. 다음 섹션을 참고하세요.
- 선택 사항: IP 화이트리스트 (선택) 입력란에 키를 사용할 수 있는 IP 주소나 범위를 쉼표로 구분해 입력합니다.
- 새 키 생성을 클릭합니다.
- API 키 생성 완료에서 키를 복사해 안전한 곳에 보관한 다음 완료를 클릭합니다.
전체 키는 한 번만 볼 수 있습니다. 키를 잃어버렸다면 새 키를 생성하고 이전 키를 폐기합니다.
API 접근 탭에 업그레이드 안내가 표시되면 플랫폼 플랜에 API 액세스가 포함되어 있지 않은 것입니다. API 엔드포인트 카드에는 요청에 사용할 기본 URL과 플랜의 일일 요청 한도가 표시되며, 한도는 00:00 UTC에 초기화됩니다.
API 키 스코프(권한)
| 스코프 | 허용하는 작업 |
|---|---|
| 커뮤니티 읽기 | 커뮤니티 프로필, 설정, 메타데이터 읽기 |
| 콘텐츠 읽기 | 게시물, 피드, 답글, 검색 결과 읽기 |
| 콘텐츠 쓰기 | 게시물과 답글 생성, 수정, 삭제 |
| 미디어 업로드 | 업로드 토큰 요청. 서명된 미디어 URL 읽기도 포함 |
| 미디어 읽기 | 기존 미디어의 서명된 URL 읽기 |
| 스페이스 읽기 | 스페이스 목록 조회 및 스페이스 세부 정보 읽기 |
| 멤버 읽기 | 멤버 조회 및 액세스 그룹을 포함한 기본 프로필 읽기 |
| 멤버 초대 | 이메일이나 초대 링크로 사람 초대 |
멤버 읽기와 멤버 초대는 민감한 권한 아래에 나열됩니다. 멤버 읽기를 사용하면 통합에서 이메일 주소가 커뮤니티에 속하는지 확인할 수 있습니다. 멤버 초대를 사용하면 통합에서 다른 초대자를 지정하지 않는 한 커뮤니티 소유자 이름으로 초대가 전송되며, 초대받은 사람은 항상 멤버로 가입합니다. API 초대에는 액세스 그룹을 포함할 수 있습니다. 액세스 그룹의 작동 방식을 참고하세요.
키의 스코프는 나중에 변경할 수 없습니다. 이전에 만든 키에는 전체(구버전) 표시가 나타날 수 있으며, 이런 키는 생성 당시에 있던 스코프만 유지합니다. 새 스코프를 사용하려면 새 키를 만드세요.
API 키 폐기하기
- API 접근 탭의 API 키에서 키를 찾습니다.
- 작업 메뉴를 열고 키 폐기를 클릭합니다.
- 확인합니다. 폐기는 되돌릴 수 없으며, 이 키를 사용하는 모든 도구가 작동을 멈춥니다.
목록에는 각 키의 상태(활성, 만료됨, 취소됨)와 마지막 사용 날짜가 표시됩니다. API 요청은 전송 로그에 표시되지 않으므로 키가 아직 사용 중인지는 마지막 사용으로 확인합니다. Slack, Discord, Zapier 연결을 해제해도 API 키는 폐기되지 않습니다.
API 키를 안전하게 보관하기
- API 키는 다른 사람이 다운로드할 수 있는 웹사이트나 앱이 아니라 서버에 보관하고, 요청은 HTTPS로 보냅니다.
- 도구마다 필요한 스코프만 가진 별도의 키를 주면, 다른 도구에 영향을 주지 않고 키 하나만 폐기할 수 있습니다.
- 도구가 고정된 주소에서 호출하는 경우 IP 화이트리스트를 추가합니다.
- 키가 유출되었을 가능성이 있으면 즉시 폐기한 다음 대체 키를 만듭니다.
API 문서를 찾는 위치
API 참조 문서에는 엔드포인트, 요청 및 응답 형식, 스코프, 오류 코드, 코드 샘플이 있습니다. API 접근 탭의 개발자 문서 카드에 있는 문서 열기 버튼을 클릭하면 mateflow.com/developers로 이동합니다. 이 링크를 개발자에게 보내세요. 개발자는 커뮤니티 계정이 없어도 되며, 플랜에 API 액세스가 포함되어 있지 않아도 이 페이지를 볼 수 있습니다.
관련 문서
이 가이드가 도움이 되었나요?