> For the complete documentation index, see [llms.txt](https://docs.podplay.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podplay.app/api/venues/proximity-access.md). # Proximity Access Proximity-based access control for courts and facilities. ## Authenticate with proximity access hardware (NFC, Bluetooth, etc.) > \ > Provides credentials for proximity-based access to doors/locks using various hardware providers.\ > Currently supports Kisi provider. Other providers return "not supported yet" error.\ > \ > Returns authentication secrets for offline-capable door access.\ > \ > Uses camelCase properties following API standards.\ > ```json {"openapi":"3.0.0","info":{"title":"PodPlay Inc API","version":"2.0"},"tags":[{"name":"Proximity Access","description":"Proximity-based access control for courts and facilities."}],"servers":[{"url":"/apis/v2","description":"Current Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"ProximityLoginRequestDto":{"type":"object","properties":{"provider":{"type":"string","description":"The proximity access provider to use for authentication.","enum":["KISI","OPEN_PATH","REMOTE_LOCK"]},"deviceBrand":{"type":"string","description":"Device brand (e.g., Apple, Samsung)"},"deviceModel":{"type":"string","description":"Device model (e.g., iPhone 15, Galaxy S24)"},"osName":{"type":"string","description":"Operating system name (e.g., iOS, Android)"},"errors":{"readOnly":true,"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDto"}}},"required":["provider","deviceBrand","deviceModel","osName","errors"]},"ValidationErrorDto":{"type":"object","properties":{"code":{"type":"string","readOnly":true},"message":{"type":"string","readOnly":true},"details":{"type":"object","readOnly":true,"nullable":true}},"required":["code","message","details"]},"ProximityLoginResponseDto":{"type":"object","properties":{"id":{"type":"number","description":"The login session ID from Kisi"},"secret":{"type":"string","description":"The authentication token used for this login"},"scramCredentials":{"description":"SCRAM credentials for offline NFC authentication","allOf":[{"$ref":"#/components/schemas/ScramCredentialsDto"}]}},"required":["id","secret","scramCredentials"]},"ScramCredentialsDto":{"type":"object","properties":{"phoneKey":{"type":"string","description":"Phone key for offline NFC authentication"},"onlineCertificate":{"type":"string","description":"Online certificate for authentication validation"}},"required":["phoneKey","onlineCertificate"]}}},"paths":{"/proximity-access/login":{"post":{"operationId":"ProximityAccessController_login","summary":"Authenticate with proximity access hardware (NFC, Bluetooth, etc.)","description":"\n Provides credentials for proximity-based access to doors/locks using various hardware providers.\n Currently supports Kisi provider. Other providers return \"not supported yet\" error.\n \n Returns authentication secrets for offline-capable door access.\n \n Uses camelCase properties following API standards.\n ","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProximityLoginRequestDto"}}}},"responses":{"200":{"description":"Returns proximity access credentials for the specified provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProximityLoginResponseDto"}}}},"400":{"description":"Bad request - invalid provider or device info"},"401":{"description":"Authentication failed - invalid PodPlay user"},"422":{"description":"Validation errors in request data"},"500":{"description":"Internal server error or proximity service unavailable"}},"tags":["Proximity Access"]}}}} ``` ## Execute proximity sync for user by email > \ > Executes the proximity sync for a specific user by email which:\ > 1\. Finds the user by email\ > 2\. Gets areas from user's membership subscription\ > 3\. Calculates sync operations (add/remove access)\ > 4\. Creates operations and processes them (ORDER mode)\ > OR returns preview of operations (PREVIEW mode)\ > \ > Can be run in PREVIEW mode to see what would be processed,\ > or ORDER mode to actually perform the operations.\ > ```json {"openapi":"3.0.0","info":{"title":"PodPlay Inc API","version":"2.0"},"tags":[{"name":"Proximity Access","description":"Proximity-based access control for courts and facilities."}],"servers":[{"url":"/apis/v2","description":"Current Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"ProximitySyncUserJobDto":{"type":"object","properties":{"type":{"type":"string","description":"The job type","enum":["PREVIEW","ORDER"]},"email":{"type":"string","description":"User email to sync"}},"required":["type","email"]},"ProximitySyncUserJobResultDto":{"type":"object","properties":{"type":{"type":"string","description":"The job type"},"email":{"type":"string","description":"User email that was processed"},"totalOperations":{"type":"number","description":"Total number of operations that would be created"},"addOperations":{"type":"number","description":"Number of ADD operations"},"removeOperations":{"type":"number","description":"Number of REMOVE operations"},"operations":{"description":"Detailed list of operations","type":"array","items":{"$ref":"#/components/schemas/ProximitySyncOperationLineDto"}},"executionTimeMs":{"type":"number","description":"Job execution time in milliseconds"}},"required":["type","email","totalOperations","addOperations","removeOperations","operations","executionTimeMs"]},"ProximitySyncOperationLineDto":{"type":"object","properties":{"operation":{"type":"string","description":"Brief description of the operation"},"action":{"type":"string","description":"The operation action","enum":["add","remove"]},"area":{"description":"Reference to the area resource","allOf":[{"$ref":"#/components/schemas/ItemRefDto"}]}},"required":["operation","action","area"]},"ItemRefDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the resource"}},"required":["id"]}}},"paths":{"/proximity-access/sync/email":{"post":{"operationId":"ProximitySyncUserJobsController_syncUserEmail","summary":"Execute proximity sync for user by email","description":"\n Executes the proximity sync for a specific user by email which:\n 1. Finds the user by email\n 2. Gets areas from user's membership subscription\n 3. Calculates sync operations (add/remove access)\n 4. Creates operations and processes them (ORDER mode)\n OR returns preview of operations (PREVIEW mode)\n \n Can be run in PREVIEW mode to see what would be processed,\n or ORDER mode to actually perform the operations.\n ","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProximitySyncUserJobDto"}}}},"responses":{"200":{"description":"Job execution completed. Returns ProximitySyncUserJobResultDto with operation summary for both PREVIEW and ORDER modes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProximitySyncUserJobResultDto"}}}},"400":{"description":"Proximity access feature disabled"},"403":{"description":"Insufficient permissions"},"404":{"description":"User not found"},"500":{"description":"Internal server error"}},"tags":["Proximity Access"]}}}} ``` ## POST /proximity-access/jobs/process-expired > ```json {"openapi":"3.0.0","info":{"title":"PodPlay Inc API","version":"2.0"},"tags":[{"name":"Proximity Access","description":"Proximity-based access control for courts and facilities."}],"servers":[{"url":"/apis/v2","description":"Current Server"}],"paths":{"/proximity-access/jobs/process-expired":{"post":{"operationId":"ProximitySyncUserJobsController_processExpired","parameters":[],"responses":{"201":{"description":""}},"tags":["Proximity Access"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podplay.app/api/venues/proximity-access.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.