인증 가이드

통합 개발을 위한 Bluebeam Developer Portal은 미국, 호주, 독일, 영국, 남동부 지역의 활성 고객, 채널 파트너 및 소프트웨어 파트너에게만 제공됩니다.

모든 Bluebeam API 엔드포인트에 대한 요청은 인증을 받아야 합니다. 앱은 OAuth 2.0을 사용하여 Bluebeam에 연결됩니다. 이 가이드에서는 앱에서 사용자를 대신하여 인증하기 위한 access_token 얻는 방법을 보여줍니다.

인증 과정을 시작하기 전에 다음 사항을 꼭 확인하세요.

  • 앱 등록

  • 리디렉션 URI 제공

  • 클라이언트 ID와 비밀번호를 저장하세요

위의 단계를 아직 거치지 않았다면 Bluebeam Developer Portal 페이지에서 시작하기를 방문하여 자세한 내용을 알아보세요.

모든 엔드포인트에 적용되는 지역별 기본 URL이 있습니다.

- 미국: https://api.bluebeam.com

- 독일: https://api.bluebeamstudio.de

- 호주: https://api.bluebeamstudio.com.au

- UK: https://api.bluebeamstudio.co.uk

- SE: https://api.bluebeamstudio.se

예를 들어, 미국에서 https://api.bluebeam.com/publicapi/v1/sessions가 발생하면 호주에서는 https://api.bluebeamstudio.com.au/publicapi/v1/sessions 가 됩니다.

승인 코드 흐름

앱의 비밀을 유지할 수 있는 경우에만 승인 코드 인증을 사용하세요(예: 앱이 사용자가 제어하는 웹 서버에서 실행되는 경우). client_secret 을 비밀번호와 마찬가지로 다루어야 합니다.

첫 번째 단계는 앱에 대한 사용자 승인을 요청하는 것입니다. 사용자를 권한 부여 엔드포인트로 리디렉션하여 Studio 자격 증명을 사용하여 로그인하고 앱에 대한 권한을 부여하라는 메시지를 표시합니다. 이렇게 하려면 다음 매개변수를 사용하여 Authorization 엔드포인트에 GET 요청을 보냅니다.

인증 엔드포인트

복사 
https://api.bluebeam.com/oauth2/authorize

요청 매개변수

매개변수는 쿼리 문자열로 전달되어야 합니다.

이름

설명

response_type

code로 설정해야 합니다

client_id

앱 등록 과정 중 수신된 클라이언트 ID( 내 앱 참조)

redirect_uri

앱 등록 과정에서 지정된 리디렉션 URI(내 앱 참조)

scope

Studio 엔드포인트에만 적용됩니다. Studio 엔드포인트 범위 목록(공백으로 구분)은 아래 표를 참조하세요.

state

앱에서 생성된 무작위 문자열입니다. Studio는 이 상태를 콜백으로 귀하의 redirect_uri 에 반환합니다. 사이트 간 요청 위조를 방지하려면 앱의 상태와 비교하여 유효성을 검사하세요.

Studio 엔드포인트 범위

범위 이름

설명

read_prime

보고를 위한 사용자의 Studio 프로젝트 및 Studio 세션에 대한 읽기 전용 액세스

full_user

사용자 소유의 Studio 프로젝트 및 Studio 세션에 대한 전체 액세스

jobs

Studio Projects에서 자동화된 작업에 액세스

offline_access

이 범위에 refresh_token을 요청하세요

토큰 새로 고침
refresh_token을 다시 받으려면 요청에서 'offline_access' 범위를 반드시 요청하세요. 아래 4단계에서 refresh_tokens에 대해 자세히 알아보세요.

범위 선택에 대한 참고 사항
범위를 선택할 때 앱이 어떤 데이터에 액세스해야 하는지 고려하세요. 보안 위험을 최소화하려면 필요한 최소한의 범위만 요청하세요.

요청 예시

복사 
GET https://api.bluebeam.com/oauth2/authorize?response_type=code&client_id=b5f9fc7c-60dd-469f-a21e-3f4a7ceb874b&redirect_uri=http://myserver.com&scope=full_prime offline_access jobs&state=myteststate

사용자 경험

사용자는 Bluebeam 로그인 페이지로 이동됩니다.

로그인 후 사용자는 '액세스 허용'을 선택하여 앱이 자신의 데이터에 액세스하도록 허용할 수 있습니다.

사용자가 '액세스 허용'을 선택하여 앱에 대한 액세스 권한을 부여하는 경우 원래 요청에서 redirect_uri 로 지정된 URL로 콜백을 받게 됩니다. 콜백이 성공하면 access_token 으로 교환해야 하는 승인 code 포함됩니다. 응답의 state 원래 요청에서 제출한 상태와 일치하는지 확인하세요. 오류가 발생한 경우 error 매개변수와 함께 리디렉션을 받게 됩니다.

응답 매개변수

매개변수는 쿼리 문자열의 일부로 수신됩니다.

이름

설명

code

access_token 으로 교환해야 하는 임시 승인 코드

state

앱에서 생성된 무작위 문자열입니다. Bluebeam은 이 상태를 귀하의 redirect_uri 에 대한 콜백으로 반환합니다. 사이트 간 요청 위조를 방지하려면 원래 요청의 상태와 비교하여 유효성을 검사하세요.

error

이 필드에는 권한 요청이 실패할 경우 발생하는 오류 코드가 포함되어 있습니다. 인증 및 권한 부여 오류에 대한 일반적인 HTML 응답 코드를 참조하세요.

응답 예시

복사 
https://www.myserver.com/?code=acf3cabd-08c1-44db-88a9-4f785ec7c6ec&state=myteststate
보안 지침
리디렉션 프로세스의 일부로 승인 코드가 사용자에게 표시되지 않도록 하세요.

승인 코드는 5분 동안만 유효합니다. 코드 및 토큰 기간 목록은 토큰 만료를 참조하세요.

이제 승인 code 받았으니 다음 단계는 Bluebeam에서 access_token 으로 교환하는 것입니다. 이렇게 하려면 아래 매개변수를 사용하여 토큰 엔드포인트에 POST 요청을 합니다.

토큰 엔드포인트

복사 
https://api.bluebeam.com/oauth2/token

요청 매개변수

매개변수는 양식 인코딩되어야 합니다.

이름

설명

grant_type

authorization_code로 설정해야 합니다.

code

이전 단계에서 반환된 승인 코드

client_id

앱 등록 과정 중 수신된 클라이언트 ID( 내 앱 참조)

client_secret

앱 등록 과정에서 발급받은 클라이언트 시크릿(내 앱 참조)

redirect_uri

앱 등록 과정에서 지정된 리디렉션 URI(내 앱 참조)

scope

공백으로 구분된 범위 포함

cURL 예제

복사 
curl [https://api.bluebeam.com/oauth2/token](https://api.bluebeam.com/oauth2/token) \
-d grant_type=authorization_code \
-d code={code returned from previous step} \
-d redirect_uri={your redirect_uri} \
-d client_id={your client_id} \
-d client_secret={your client_secret} \
-d scope= offline_access {your requested scopes} \
-X POST

응답 예시

복사 
{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJraWQiOiIybEczWnV2Q1pHRDFQX0FYclk4U0YyVVdmU2x3WHFpNWxZcUFzaHc4M05rIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjJ0Ml9nQWtxc2RvcDFWcWR1ajdLVUZwbXdNT1ZvU1VxcmZWVm5TOUZuMU0iLCJpc3MiOiJodHRwczovL3NpZ25pbi5ibHVlYmVhbS5jb20vb2F1dGgyL2F1c2JlcGh2azBlYkk3T09UNHg3IiwiYXVkIjoiYXBpOi8vYmItYWNtIiwiaWF0IjoxNzA4OTcwMzM2LCJleHAiOjE3MDg5NzM5MzYsImNpZCI6IjBvYWc2aGFjYWhnRUtqM0loNHg3IiwidWlkIjoiMDB1YngyeThtMDlwelVKRms0eDciLCJzY3AiOlsiZnVsbF9wcmltZSJdLCJhdXRoX3RpbWUiOjE3MDg5NzAzMTcsInN1YiI6InRvcnlhZGFtc0BwbS5tZSIsImJiaWQiOiJkNzE3MGZmYy03ZjlmLTQxZjYtOTY2ZS0xOTg1NTJlNzQwOTAifQ.S8m-cIfq8m19GtJ67skC8WM4bMWvJbAAr74A7g3HrUmH66M1_MN4MaDWjgcYjNFOI1zWsiZ5qm1HODLYY92lgUfzGuiYnkvpiJEKBtIUzLec2E2uEGE5HuW6FbyiX_SdGnSKeHlTr_FfiWGcpTYF816rI6q72kFm2J_3pKA-z_6REkNhI7qouRDRIHqT88tOE9KcjrF8_HsRAuixYAOlcGoVq3rvupvNVVaekoLyGiGWovXdJ-Wrx-1pKo0r7px2_Y8ew9OWEgYCX0u8pQvvPB6HAfF8dNCGTz_jFw9MbItu70rIniDoycILZKNxOcdKTLsCK7AC5doBcg9dV0OrHQ",
  "scope":"full_user offline_access",
  "refresh_token":"f5Mj16b7eVXwlY3Axc7TH2oEG_FPV1BrY05ht0uin6B"
}

응답 매개변수

이름

설명

token_type

이것은 항상 "Bearer"가 될 것입니다

expires_in

토큰이 만료될 때까지의 시간(초)

access_token

사용자를 대신하여 요청을 하는 데 사용되는 전달자 토큰

refresh_token

사용자가 다시 로그인하지 않고도 새로운 액세스 토큰 및 새로 고침 토큰으로 교환할 수 있습니다.

scope

요청된 범위의 공백으로 구분된 목록

access_token 받으면 이를 사용하여 API에 액세스할 수 있습니다. access_token 사용하려면 Authorization 헤더에 포함하세요.

복사 
Authorization: Bearer {a valid access_token}

승인 헤더를 보낼 때 "Bearer"의 "B"가 대문자인지 확인하세요. "Bearer"를 대문자로 쓰지 않으면 오류가 발생합니다.

액세스 토큰

access_token 사용자를 대신하여 요청을 할 수 있게 해주는 실제 문자열입니다. Bluebeam API에 대한 모든 요청에는 유효한 access_token 포함되어야 합니다.

각 access_token 60분 동안 유효합니다. access_token 만료된 후에는 사용자가 유효한 refresh_token 교환하여 다시 로그인할 필요 없이 새로운 access_token 발급받을 수 있습니다.

 

토큰 새로 고침

새로고침 토큰의 목적
새로 고침 토큰은 사용자가 모든 요청에 대해 로그인할 필요 없이 Bluebeam API에 대한 인증된 요청을 할 수 있는 편리하고 안전한 방법입니다.
새로 고침 토큰은 항상 1) 1시간 동안 지속되는 액세스 토큰과 2) 최소 7일에 한 번 사용하는 한 유효한 새로운 새로 고침 토큰으로 교환됩니다.
이론적으로 사용자가 1단계에서 수동으로 액세스 권한을 부여하면 유효한 새로 고침 토큰을 액세스 토큰으로 계속 교환할 수 있으므로 사용자는 다시는 수동으로 인증할 필요가 없습니다. 단, 최소 7일에 한 번씩 새로 고침 토큰을 교환해야 합니다.

첫 번째 refresh_token 얻으려면 1단계에서 offline_access 범위를 요청하는 것이 좋습니다. 그러면 refresh_token 도 받게 됩니다.

마지막 access_token 받은 후 3600초 이내에 refresh_token 을 새로운 access_token 으로 교환하세요. refresh_token access_token 으로 교환하면 새로운 refresh_token 발급됩니다.

1시간 후에 만료되는 access_token 과 달리 refresh_token 은 최소 7일에 한 번씩 사용하면 무기한 유효합니다. refresh_token 은 7일 이내에 사용되지 않으면 무효화됩니다.

refresh_token 암호화하여 안전한 곳에 보관하세요. refresh_token 이 분실되거나 만료된 경우 OAuth 흐름의 시작 부분부터 사용자에게 다시 인증하도록 요청해야 합니다.

refresh_token 새로운 access_token 과 refresh_token 으로 교환하려면 토큰 엔드포인트에 POST 요청을 합니다.

토큰 엔드포인트

복사 
https://api.bluebeam.com/oauth2/token
보안 지침
헤더에 다음의 base64 인코딩된 문자열을 포함합니다: "{your client_id}:{your client_scret}" — 노트로 콜론은 스페이스 없이 존재해야 합니다. 아래 예시를 참조하세요.

요청 매개변수

매개변수는 양식 인코딩되어야 합니다.

이름

설명

grant_type

refresh_token으로 설정해야 합니다.

refresh_token

authorize 호출 중에 반환된 값으로 설정해야 합니다.

cURL 예제

복사 
curl [https://api.bluebeam.com/oauth2/token](https://api.bluebeam.com/oauth2/token) \
-H Content-Type: application/x-www-form-urlencoded \
-H Authorization: Basic {base64 encoded string of client_id:client_secret} \ 
-d grant_type=refresh_token \
-d refresh_token={your refresh_token} \
-X POST
보안 지침
refresh_token을 비밀번호처럼 취급하세요. 암호화된 상태로 안전한 장소에 저장해야 합니다.

새로 고침 토큰 취소
새로 고침 토큰은 취소될 수 있습니다. refresh_token이 취소되면 사용자는 현재 access_token이 만료된 후 다시 인증을 받아야 합니다.

토큰 만료

  • 승인 코드는 5분 후에 만료됩니다.

  • 액세스 토큰은 60분 후에 만료됩니다.

  • 새로 고침 토큰은 최소 7일에 한 번 이상 사용되지 않으면 만료됩니다.

권한 부여 및 인증 오류

어떤 종류의 오류가 발생하는지 알려주시면 문제 해결에 도움을 드리겠습니다.

일반적인 HTML 응답 코드

HTTP 코드

메시지

정의

200

확인

요청이 성공했습니다.

201

생성됨

요청이 성공하여 새로운 리소스가 생성되었습니다.

204

콘텐츠 없음

서버가 요청을 이행했으므로 엔티티 본문을 반환할 필요가 없습니다.

400

잘못된 요청

잘못된 구문으로 인해 요청을 이해할 수 없습니다.

401

무단

요청에는 사용자 인증이 필요합니다. 액세스 토큰을 전달한 후에 이 메시지를 받았다면 새로운 액세스 토큰을 받아보세요. 그래도 401을 받으면 범위를 확인하세요. 계속해서 401 오류가 발생하는 경우, integrations@bluebeam.com으로 지원팀에 문의하세요.

403

금지됨

서버는 요청을 이해했지만 이를 이행하기를 거부하고 있습니다.

404

찾을 수 없음

서버가 Request-URI와 일치하는 것을 찾지 못했습니다.

409

충돌

리소스의 현재 상태와 충돌이 발생하여 요청을 완료할 수 없습니다.

 

또한 참조하세요:

리소스

Revu 21

Developer Portal

Developer Portal

이 Developer Portal 가이드는 앱에서 사용자를 대신하여 인증할 수 있도록 access_token을 얻는 방법을 안내합니다.