Skip to content

Qosımşalar üşin OAuth 2.0

OAuth 2.0 qosımşağa paýdalanwşı atınan Planfix-ke parolʹ suramaý nemese saqtamaý qol jetkizwge mümkindik beredi.

Planfix mindetti türde PKCE S256 qoldanılatın Authorization Code ağınin (flow) paýdalanadı. OAuth arqılı REST API nemese Planfix MCP serveri-ge qosılwğa boladı.

Daýın AI klïyentin qosqıñız kelse, aldımen Planfix MCP parağına qarañız. Eger kirwdi öz esep jazbañızda basqaratın bolsañız, OAuth and MCP applications in an account parağına ötiñiz. Partnerler men köpeseptik ïntegracïyalardı jasawşılarğa OAuth applications for partners paýdalı boladı.

Qosımşanı tirkewdiñ opcïyaları

Opcïya Qaşan qoldanw qajet Qaý jerde jumıs isteýdi
Eseptik jazbağa tïyesili qosımşa Ïntegracïya bir eseptik jazbağa arnalğan jäne klïyentke aldın ala anıqtalğan client_id qajet. Tek onı tirkegen eseptik jazbada.
Serikteske tïyesili qosımşa Birdeý qosımşa birneşe klïyenttik eseptik jazbalarğa qosılwı kerek. Qawipsizdik sayasatı nemese äkimşi ruqsat etken eseptik jazbalarda.
Avtomattı MCP klïyentin tirkew MCP klïyenti Client ID Metadata Document (CIMD) nemese Dynamic Client Registration (DCR) qoldaýdı. Tirkew özimen birge eseptik jazbağa qoljetimdilik bermeýdi. Qosımşa äli de tañdalğan eseptik jazbada ruqsat etilwi tïis.

CIMD jäne DCR tek MCP qosılımdarı üşin qoljetimdi. REST API üşin eseptik jazbağa tïyesili nemese serikteske tïyesili qosımşanı paýdalanıñız.

OAuth soñğı nükteleri (endpoints)

Jaña ïntegracïyalar ğalamdıq (global) soñğı nüktelerdi paýdalanwı kerek. Osı URL-derge eseptik jazba atawı endirilmeýdi: paýdalanwşı avtorïzacïya kezinde eseptik jazbanı tañdaýdı.

Maqsat Adres
Issuer https://auth.planfix.com
Authorization https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
User information https://auth.planfix.com/oauth/userinfo
Token revocation https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration https://auth.planfix.com/oauth/register

Avtorïzacïya serveriniñ metaderekteri standarttı soñğı nüktelerde qoljetimdi: 

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

Redirect URI-lar

Redirect URI qosımşa parametrlerinde tirkelwi tïis. Avtorïzacïya surawında jiberilgen män tirkelgen URI-ğa säýkes bolwı kerek.

Ruqsat etilgender:

  • https URL-darı;
  • http URL-darı tek loopback xosttar (mısalı, localhost nemese 127.0.0.1) üşin ğana.

Loopback URI-de port dïnamïkalıq bolwı mümkin, biraq sxeması, xostı, jolı jäne suranıs (query) säýkes bolwı tïis. URL fragmentteri jäne URL işindegi paýdalanwşı twralı aqparatqa ruqsat joq.

Qoljetimdilik deñgeýleri

Qosımşa aldın ala ruqsat etilgen qoljetimdilik deñgeýleri nemese scopes ğana aladı. Tolıq tizim üşin REST API access levels qarañız.

Suralğan jïıntıq qosımşağa tirkelgen scope-tardıñ kömeskisi (subset) bolwı tïis. Qosımşa scope-tarı Planfix işindegi paýdalanwşınıñ ruqsattarın keñeýtpeýdi: qosımşa tek qosqan qızmetkerge qoljetimdi derekterge ğana qol jetkize aladı.

Basqarılatın qosımşalarğa qosımşa qızmettik scope-tar userinfo, openid, jäne email beriledi.

Paýdalanwşı avtorïzacïyası

code_verifier jäne onıñ SHA-256 türlendirilwi code_challenge qurıñız, sodan keýin avtorïzacïya soñğı nüktesin brawzerde aşıñız.

REST API mısalı: 

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

MCP üşin däl MCP serveriniñ URL-in körsetetin resource parametrin qosıñız: 

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp
Parametr Sïpattaması
client_id Tirkelgen qosımşanıñ ïdentïfïkatorı. CIMD üşin bul klïyent metaderekter qujatınıñ URL-i.
redirect_uri Ruqsat etilgen Redirect URI-lardıñ biri.
response_type code bolwı qajet.
scope Bos ornımen bölingen qajetti ruqsattar. Bul parametr REST API üşin mindetti. MCP klïyenti onı jibermewi mümkin — ondaý jağdaýda qosımşağa ruqsat etilgen scope-tar qoldanıladı.
state Surawdı almastırwdan qorğaw üşin kezdeýsoq män. Qaýta bağıttalğannan keýin qosımşa onı tekserwi tïis.
code_challenge code_verifier-diñ SHA-256 xéşiniñ padding-sız base64url türi.
code_challenge_method Tek S256 qoldaw körsetiledi.
resource MCP üşin däl URL https://mcp.planfix.com/mcp. REST API üşin bul parametrdi jibermeñiz.

Paýdalanwşı eseptik jazbanı tañdap, jüýege kiredi jäne suralğan ruqsattardı qaraýdı. Eseptik jazbağa tïyesili qosımşa tikeleý öziniñ ïyelik etetin eseptik jazbasın aşadı. Eger qawipsizdik sayasatı äkimşi maquldawın talap etse, Planfix tïisti qadamdı körsetedi. Äkimşi qosımşanı maquldap, onı bir äreketpen qoswı mümkin.

Tabıstı avtorïzacïyadan keýin Planfix brawzerdi redirect_uri-ge qaýta bağıttaýdı: 

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Avtorïzacïya kodı bir rettik jäne 10 mïnwt işinde jaramdı.

Token alw

/oauth/token-ke POST surawın application/x-www-form-urlencoded türinde jiberiñiz: 

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

MCP üşin avtorïzacïya surawında qoldanılğanmen däl sol resource parametrin qaýtalañız.

Pablïk (public) klïyent surawdı sekretsiz jiberedi. Konfïdencïaldı (confidential) klïyent client_secret_basic arqılı nemese suraw denesinde client_id jäne client_secret parametrlerimen awtentïfïkacïyalanadı.

Mısal jawap: 

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

REST API üşin jawapta qosımşa account_name, account_domain, jäne account_url boladı. Osı mänderdi saqtap, REST API surawlarında tañdalğan eseptik jazbanıñ URL-in paýdalanıñız.

Access token 24 sağatqa jaramdı. Ol paýdalanwşığa, eseptik jazbağa, qosımşağa, scope-tarğa jäne resource-qa baýlanıstı. MCP üşin berilgen token tikeleý REST API-de qoldanılmaýdı, jäne REST API üşin berilgen token MCP-de qoldanılmaýdı.

REST API-men tokendi paýdalanw

Tokendi Authorization taqırıbında jiberiñiz: 

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Token almastırw kezinde authorization code-tı aýırbastaw kezinde qaýtarılğan eseptik jazba URL-in qoldanıñız. Tek ruqsat etilgen scope-tarmen qamtılğan ädisterge qoljetimdilik bar. OAuth tokenderi eseptik jazba josparına jäne standarttı REST API limits şektewlerine bağınadı.

Paýdalanwşı twralı aqparat

userinfo surawı openid scope-ın talap etedi: 

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

email scope-ı bar kezde mısal jawap: 

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Ğalamdıq OAuth avtorïzacïyası eseptik jazbanıñ qızmetkerleri üşin qoljetimdi. Planfix id_token şığarmaýdı; paýdalanwşı derekterin alw üşin userinfo-dı surañız.

Tokenderdi jañartw

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

MCP üşin däl sol resource mänin jiberiñiz. Konfïdencïaldı klïyent öz sekretimen awtentïfïkacïyalanwı tïis.

Planfix jaña access token jäne jaña refresh token qaýtaradı. Aldıñğı refresh token derew jaramsız boladı, sondıqtan qosımşa saqtalğan mändi atomarlı türde almastırwı tïis.

Tokendi qaýtarw (revoke)

Klïyent refresh token-dı /oauth/revoke arqılı qaýtarıp tastaý aladı: 

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Paýdalanwşı öz baýlanısın öziniñ paýdalanwşı kartasındağı Session management böliminen de öşire aladı. Äkimşi üşinşi tarap qosımşasınıñ maquldawın bükil eseptik jazba üşin qaýtarwı mümkin. OAuth and MCP applications in an account qarañız.

Bar ïntegracïyalarmen üýlesimdiligi

https://account.planfix.com/api/v2/oauth/authorize, /token, jäne /userinfo sïyaqtı tenant (tenant) soñğı nükteleri naqtı eseptik jazbağa baýlanğan burınnan bar ïntegracïyalar üşin jumısın jalğastıradı.

Jaña ïntegracïyalar üşin ğalamdıq soñğı nüktelerdi paýdalanıñız. Olar standarttı metaderekterdi tabwdı, eseptik jazbanı tañdawdı jäne MCP-ni qoldaýdı. Bir OAuth seansına ğalamdıq jäne tenant soñğı nüktelerin aralastırıp qoldanbañız.

Qawipsizdik boýınşa usınıstar

  • Ärqaşan PKCE S256 qoldanıñız jäne state-ti tekseriñiz.
  • Mobïlʹdi, desktop jäne brawzer qosımşaları üşin sekretsiz (public) klïyent paýdalanıñız.
  • Sekret serverde senimdi türde saqtalatın kezde ğana konfïdencïaldı klïyentti paýdalanıñız.
  • Qajet mïnïmwm scope-tardı surañız.
  • Access token-dardı, refresh token-dardı, authorization code-tardı, code_verifier-di nemese klïyent sekretterin jwrnaldarğa jazbañız.
  • Refresh token-dar men klïyent sekretterin şïfrlanğan saqtaw ornında saqtañız.
  • Jawaptağı iss-ti tekseriñiz jäne tek kütilgen Planfix issuer-in ğana qabıldañız.

Mümkin qateler

Qate Sebebi
invalid_client Klïyent belgisiz nemese öşirilgen, klïyent sekreti durıs emes, nemese qosımşa tañdalğan eseptik jazbada qoljetimdi emes.
invalid_grant Avtorïzacïya kodı nemese refresh token jaramsız, merzimi ötken, burın qoldanılğan, nemese klïyentke, redirect URI-ge, PKCE derekterine nemese resource-qa säýkes kelmeýdi.
invalid_scope Suraw qosımşağa ruqsat etilmegen scope-tı qamtïdı.
invalid_target resource qoldaw körsetilmeýdi nemese surawlar arasında özgergen.
access_denied Paýdalanwşı qosılwdan bas tarttı nemese eseptik jazba sayasatı qosımşanı ruqsat etpeýdi.
HTTP 401, invalid_token Access token belgisiz, merzimi ötken nemese qaýtarılğan.
HTTP 403, insufficient_scope Operacïya üşin qajet scope tokende joq.

Ötw (Go To)

«http://planfix.com/kk/help/index.php?title=Қосымшалар_үшін_OAuth_2.0&oldid=7898» betınen alynğan